Part Four: Software Distribution List of Topics 19.0 BrightWorks Distribution 19.1 About BrightWorks' Software Distribution Capability 19.2 How This Part is Organized 19.3 Software Distribution Concepts 19.4 BrightWorks' Software Distribution Modules 19.4.1 BrightWorks Console/Administrative Program 19.4.2 Update Program 19.5 Distribution Configuration Options 19.5.1 Running the Update Program 19.5.2 Automating the Update Program 19.6 Quick Start to Preparation and Setup for Software Distribution 20.0 Filesets 20.1 Introduction 20.1.1 Fileset Features 20.1.2 Access to Fileset Functions 20.1.3 What's in this Chapter 20.2 The Fileset Directory 20.2.1 Defining a Fileset Directory 20.3 Creating Filesets 20.4 Managing Filesets 20.4.1 Editing Filesets 20.4.2 Renaming Filesets 20.4.3 Copying Filesets 20.4.4 Deleting Filesets 21.0 Scripts 21.1 Introduction 21.1.1 Script Features 21.1.2 Access to Script Functions 21.1.3 What's in this Chapter 21.2 Creating Scripts 21.3 Compiling Scripts 21.4 Managing Scripts 21.4.1 Editing Scripts 21.4.2 Renaming Scripts 21.4.3 Copying Scripts 21.4.4 Deleting Scripts 21.4.5 Incorporating BrightWorks Scripts 22.0 Software Distribution Script Language 22.1 Introduction 22.1.1 What's in this Chapter 22.2 Notes on Syntax 22.3 Script Functions 22.3.1 Type of Functions 22.3.2 User-defined Variables 22.4 DOS Functions 22.5 Easy System File Functions 22.6 Windows System File Functions 22.7 Miscellaneous Functions 22.8 Rules and System Variables 22.8.1 System Variables 22.8.2 String Type Rules: 22.8.3 Integer Type Rules: 22.9 DOS Error Codes 23.0 Scopes 23.1 Introduction 23.1.1 Scope Features 23.1.2 Access to Scope Functions 23.1.3 What's in this Chapter 23.2 Creating Scopes 23.3 Scope Queries 23.3.1 Creating a New Query 23.3.2 Editing a Query 23.3.3 Deleting a Query 23.3.4 Applying a Query to the Scope 23.3.5 Removing a Query from the Scope 23.3.6 Creating a Complex Query 23.4 Managing Scopes 23.4.1 Renaming Scopes 23.4.2 Copying Scopes 23.4.3 Deleting Scopes 24.0 Packages 24.1 Introduction 24.1.1 Package Features 24.1.2 Access to Package Functions 24.1.3 What's in this Chapter 24.2 Creating and Editing Packages 24.2.1 Editing Packages 24.3 Managing Packages 24.3.1 Prioritizing Packages 24.3.2 Renaming Packages 24.3.3 Activating/Deactivating Packages 24.3.4 Deleting Packages 24.4 The Package Timer 25.0 Monitoring Software Distribution 25.1 Introduction 25.1.1 Access to the Software Distribution Log 25.1.2 What's in this Chapter 25.2 The Software Distribution Log 25.2.1 Viewing Log History Details 19.0 BrightWorks Distribution Welcome to BrightWorks' distribution features which enable software and script distribution from a central location. NOTE: This chapter pertains to BrightWorks. 19.1 About BrightWorks' Software Distribution Capability BrightWorks' software distribution capabilities provide a method for distributing software packages and modifying workstation configuration files from a central location. The software distribution features facilitate consistency among the workstations across your local area network and improve the productivity of the LAN Administrator. Distributing software and modifying workstation configuration files from a central location on your network allows the LAN Administrator to easily do the following: o update system executables and/or drivers (e.g., operating systems, network drivers) o update system files (e.g., AUTOEXEC.BAT, CONFIG.SYS, WIN.INI, network login script) o install and update software on user workstations across the local area network NOTE: BrightWorks' Software Distribution capabilities can be used to distribute software and/or scripts to any workstation in the BrightWorks local site (i.e., the site which identifies the Fusion program directory). Sites are discussed in detail in section 13.2.1 entitled "Maintaining LAN Sites." 19.2 How This Part is Organized The following table lists the chapters in this part of the BrightWorks manual: CHAPTER DESCRIPTION 19.0 Introduction Presents an overview on the use of BrightWorks' software distribution capabilities. Also provides instructions on running and automating the distribution update program. 20.0 Filesets Presents the procedures for managing filesets, including creating, editing, renaming, copying and deleting. 21.0 Scripts Presents the procedures for managing scripts, including creating, editing, renaming, copying and deleting. 22.0 Software Distribution Lists the variables and rules for each Script Language function in the BrightWorks scripting language. 23.0 Scopes Presents the procedures for managing scopes, including creating, editing, renaming, copying and deleting; also discusses creating and managing queries to assist in scope definition. 24.0 Packages Presents the procedures for managing packages, including creating, editing, renaming, copying and deleting. 25.0 Monitoring Software Presents the procedures for viewing and Distribution managing the Software Distribution Log History. NOTE: Because BrightWorks' software distribution capabilities are provided with the inventory capabilities, the procedures for generating distribution reports are discussed throughout Chapter 18 of this manual. 19.3 Software Distribution Concepts An understanding of the following concepts will help you in gaining full advantage of BrightWorks' software distribution capabilities: o Fileset - A file that contains one or more compressed files. Each compressed file may also indicate a target directory structure in which the file should be decompressed. For example, assume a fileset named NEW_INI_FILES. The fileset might consist of two files: WIN.INI and SYSTEM.INI which have been defined to be decompressed into a target directory named PUB\WIN.310. o Script - A sequence of one or more commands which define an operation to be performed on a workstation receiving a distribution. For example, a script might include the commands to add a new group to the Windows Program Manager, to copy file(s) from one location to another, or to change parameters within certain files. o Scope - A group of one or more workstations that have been identified to receive a distribution. For example, to distribute a script to all 386 workstations, you must create a scope which includes the 386 workstations. o Package - The distributed object which contains scheduling information, as well as a fileset and/or script and a scope. The package being created is named "Updated INI Files," as indicated in the dialog box title bar. The package is scheduled to be distributed on 6/30/1994. The package consists of the fileset named "NEW_INI_FILES," which will get distributed to all nodes included in the scope named "LOCAL NODES." The following key features help you distribute software across your LAN: o Creating filesets which include files to be installed on remote workstations. o Creating scripts to be executed by remote workstations. o Defining scopes of workstations to receive distributed packages. o Creating and scheduling packages which consist of a scope and one fileset and/or one script. o Monitoring package progress via the Software Distribution Log History dialog box. 19.4 BrightWorks' Software Distribution Modules The BrightWorks software distribution capabilities interact with two major functional modules. As an introduction to software and script distribution, this section briefly describes the following modules: o BrightWorks console and administrative functions o Remote workstation update program (SDUPDATE.EXE) NOTE: BrightWorks' software distribution capabilities are provided with the inventory capabilities discussed in Part Three of this manual. 19.4.1 BrightWorks Console/Administrative Program BWORKS.EXE is the BrightWorks console and administrative program. This program provides access to all BrightWorks capabilities. This main module is a Windows-based program and is intended to be used by the LAN network manager to perform all software distribution functions. The software distribution functions available from the BrightWorks console include: o Scope definition and management o Script creation and management o Package creation, scheduling and management o Pre-defined and custom distribution report generation 19.4.2 Update Program The update program (SDUPDATE.EXE) must be executed from each remote workstation to enable the workstations to receive the distributed packages they have been sent. Upon BrightWorks installation, the update program is copied into the BWORKS program directory. The update program is DOS-based and must be executed from the machine which is to be updated. To ensure that SDUPDATE.EXE is executed on a regular basis, the command can be placed in the system login script. Refer to the next section entitled "Distribution Configuration Options." NOTE: WSDUPD.EXE is the BrightWorks update program which handles the script functions related to installing Windows software. This program must not be directly run by the user--it is automatically loaded when the ADDGROUP, ADDITEM or SCHEDULEWIN Windows System File script functions are used. Refer to section 22.6 entitled "Windows System File Functions." 19.5 Distribution Configuration Options The update program SDUPDATE.EXE must be run from each workstation in order for it to receive the distributed packages it has been sent. Upon BrightWorks installation, the update program is copied into the BWORKS program directory. The SDUPDATE program's syntax is as follows: SDUPDATE [drive:[\path]] in which drive and path are optional parameters. The brackets are not typed. Consider the following examples: Example Result SDUPDATE SDUPDATE will look in the current directory. SDUPDATE F: SDUPDATE will look in the current directory on drive F:. SDUPDATE F:\path SDUPDATE will look in the directory F:\path. NOTES: a - The Btrieve Record Manager must be loaded before running SDUPDATE.EXE. Refer to the section entitled "Consider Improving BrightWorks' Database Performance" in Chapter 12 of this manual for a discussion on the Btrieve options. b - When running the Brequestor, BSPXCOM and BROUTER must also be loaded on the file server. For details on loading these programs, refer to your Novell documentation. c - When running SDUPDATE.EXE in a DOS box, you must load another session of BREQUEST by entering the following command: BREQUEST /D:17000 /L After running SDUPDATE, end the additional session by issuing the ENDBTRV command. 19.5.1 Running the Update Program Use the following procedure to manually run the update program at a workstation. 1. At the workstation which is to receive the distributed package, load the Btrieve Record Manager. Either Btrieve or Brequest can be used. Refer to section 12.6.3 entitled "Consider Improving BrightWorks' Database Performance" for a discussion on the Btrieve options. 2. Make the BrightWorks directory your current directory. Use the DOS CD command to change into the BWORKS program directory, or map a physical drive to the BWORKS directory. 3. Execute the SDUPDATE.EXE program. For example, enter the following at the DOS command line: SDUPDATE Upon executing SDUPDATE, several messages will display at the workstation. If the user has not been given the option to refuse the update or change the installation path, then the update program will continue automatically (e.g., the package's script or fileset will be installed at the workstation). a. If you are given the option of refusing the package, then the prompt displays. To install the package at this time, type . To install the package another time (e.g., the next time the update program is run), type . NOTE: If the date or maximum number of times has expired and the package is configured to 'force upgrade,' then the package will be installed regardless of the user's response to this prompt. b. If you are given the option of overriding the installation path, then the prompt displays. To override the default installation path, type . To accept the default installation path, type . If you type to override the default installation path, you are prompted to specify a new installation path. Type the new path and press the key. The update program continues, and the package is installed. 19.5.2 Automating the Update Program To ensure that SDUPDATE is executed on a regular basis, the command can be placed in the system login script. The following example illustrates SDUPDATE being executed from within the system login script. (Refer section 35.0 for instructions on configuring the Btrieve NLM or VAP.) .... MAP G:=SERVER/SYS:FUSION DRIVE G: #BREQUEST /D:17000 #SDUPDATE #ENDBTRV .... where G:=SERVER/SYS:FUSION is the drive ID and complete path where the BrightWorks files and update program are stored. 19.6 Quick Start to Preparation and Setup for Software Distribution This section provides the steps necessary to successfully distribute software. 1. Create a FILESET which will include files to be installed on the remote workstation. For example, the FILESET might include the following files necessary to update the PC to run Windows: LAN Driver, IPXODI, LSL, NETX, HIMEM, SMARTDRIVE, EMM286 & MOUSE. See section 20.3 entitled "Creating Filesets." 2. Create SCRIPTS to be executed by remote workstations or modify canned scripts to meet your needs to complete certain tasks. See section 21.4.5 entitled "Incorporating BrightWorks' Scripts." The following files are specifically recommended: a. AUTORLP.SCR replaces the AUTOEXEC.BAT file. b. CFGRPLMT.SCR replaces the CONFIG.SYS file. c. WININST.SCR Windows Network Installation. NOTE: These scripts will require minor modifications to meet your specific environment requirements (e.g., drive mappings, local Windows install, etc.). 3. Define SCOPES of workstation to receive distributed packages. See section 23.2 entitled "Creating Scopes." Apply queries to scopes (e.g., who will receive the packages based on a criteria). See section 23.3 entitled "Scope Queries." 4. Create and schedule PACKAGES which will consist of a scope, a fileset, and/or one script. See section 24.2 entitled "Creating and Editing Packages." 5. Run SDUPDATE from the System Login Script to distribute the PACKAGE. Suggested method: MAP F:=SERVER\VOL:BWORKS DRIVE F: #BREQUEST /D:17000 #SDUPDATE #ENDBTRV MAP DEL F: See section 19.5 entitled "Distribution Configuration Options." 6. Monitor Software Distribution by viewing the Distribution Log. The history log provides a summary of all scheduled packages. See section 25.2 entitled "The Software Distribution Log." 20.0 Filesets Chapter 19 provided an introduction to BrightWorks' software distribution capability. This chapter discusses the creation and management of filesets--the set of files to be installed on a remote workstation. NOTE: This chapter pertains to BrightWorks. 20.1 Introduction A fileset is a set of files, stored in compressed format, to be installed on a remote workstation. Distributing filesets from a central location simplifies a System Administrator's job. Instead of physically moving from workstation to workstation to install or upgrade application files, the Administrator only needs to centrally distribute one fileset consisting of the application files. Upon receipt at a remote workstation, the fileset contents are decompressed and copied onto the workstation's hard drive. 20.1.1 Fileset Features In addition to containing a number of files to be distributed, filesets can be defined to create a target directory structure. For example, if you create a fileset which includes all files for Windows 3.1, you must also define the contents of the SYSTEM subdirectory. BrightWorks can do this for you automatically by including the full path name of every file included in the fileset. Filesets and scripts are a powerful combination. Consider the following examples: o Packaging the latest WIN.INI file with a script which determines whether the existing WIN.INI file is outdated. The script will also copy the new WIN.INI if an old file is detected. o Packaging the Novell IPXODI files and sending them to the scope of nodes using IPX. After the fileset is decompressed in the target directory, the script will update the AUTOEXEC.BAT file to reflect the use of IPXODI. Filesets can be stored, used and reused as a resource within BrightWorks. An administrator can create a new fileset, as well as edit, copy, rename and delete a fileset. The steps for each procedure are provided in this chapter. 20.1.2 Access to Fileset Functions Most fileset functions are accessed by choosing the Filesets command from the Tools menu. The Filesets dialog box displays listing all available filesets. The process of defining a directory in which filesets are saved (the "default fileset directory") is performed by choosing the Distribution command from the Administration menu. From the sub-menu that displays, choose the Preferences command. 20.1.3 What's in this Chapter The following chart describes the sections in this chapter: SECTION DESCRIPTION The Fileset Directory Discusses the fileset directory, and describes the procedures for its definition. Creating Filesets Describes procedures for defining new filesets. Managing Filesets Describes procedures for editing, renaming, copying and deleting filesets. 20.2 The Fileset Directory The fileset directory defines the path in which filesets are stored. Upon saving a fileset, a copy of the files that are included in the fileset are compressed. They are stored in a file which is placed in the fileset directory defined at the time the fileset is saved. For example, if your fileset directory is defined as F:\FUSION\FILESETS, then the filesets that you create will be stored in the F:\FUSION\FILESETS directory. 20.2.1 Defining a Fileset Directory Use the following procedure to define the directory in which filesets should be stored. 1. Choose the Distribution command from the Administration menu. From the sub-menu that displays, choose the Preferences command. The Preferences dialog box displays. 2. Choose the Browse button to define the pathname into which the compressed filesets are to be stored. The Path Browse dialog box displays enabling you to select from the lists of Drives and Directories. Click on the Drives and Directories fields to select the desired pathname. 3. When the pathname is selected, choose the OK button. The Path Browse dialog box closes, and the selected pathname displays in the Path to Filesets field of the Preferences dialog box. 4. Choose the Save button to define the fileset directory. All saved filesets will be stored in the defined directory. NOTE: The fileset directory instructs the update program as to where the filesets are located. As a result, changing the fileset directory after you have created filesets and included them in packages can invalidate those packages. If you change the default directory, you must also copy all fileset files (*.SET) into the new fileset directory. Be sure that each user has the same drive letter mapped to the same server/volume specified in the Preferences dialog box. Also, you cannot store filesets on a non-network drive. 20.3 Creating Filesets Use the following procedure to create a new fileset. 1. Choose the Filesets command from the Tools menu. The Filesets dialog box displays listing the names of all defined filesets. 2. Choose the New button. The New Fileset dialog box displays prompting you to enter a name for the new fileset. 3. Enter the new fileset name, and choose the OK button. A fileset name can be up to 80 characters, and all typed characters are valid. Upon choosing the OK button, the Edit Fileset dialog box displays prompting you to define the contents of the new fileset. The fileset name being created or edited displays in the title bar of the Edit Fileset dialog box. The name of the fileset being created is "1994 Budget Files." For each file included in the fileset, the following information displays: File Name, Original Size, Compression Ratio, Date, Time, and Path. The file list area is empty for new filesets. The Filename field in this dialog box displays the name of the file which will hold the compressed fileset. Upon saving the fileset, a compressed copy of all of the listed files will be stored in the file named "1994BUDG.SET." This file is automatically created by BrightWorks when the fileset is created. It is stored in the fileset directory which is currently defined. 4. To add a file to the fileset, choose the Add button. The Add File dialog box displays. This dialog box is a standard Windows dialog box used for opening, selecting and browsing files. 5. Make selections from the Directories and Drives lists to find the file(s) to include in the fileset. For example, choose the Drives down arrow button, and click on Drive C: to display the directories on drive C. From the list of directories which displays, click on one to display its file list. 6. Select a file(s) from the File Name list. Multiple files can be selected using the Windows extended select procedures (i.e., hold down the or key while selecting files). 7. To include the selected file(s)' path in the Edit Fileset dialog box, enable the Include Path option. Placing a checkmark in this field causes the full pathnames of each selected file to be listed in the Edit Fileset dialog box. (Step #9 below provides the option to instruct the fileset to create the directory structure at the receiving workstation.) 8. Choose the OK button. Upon choosing the OK button, the selected files are listed in the Edit Fileset dialog box. Only the File Name and Path information display at this time. The other fields are not available until the fileset is saved. 9. Enable or disable the Create Directory Structure option. Enabling this option causes the full pathnames of each file listed in the Edit Fileset dialog box to be created at the receiving workstation. For example, assume that this option is enabled and a file is listed in the Edit Fileset dialog box as \USER\MARY\INVOICE.DOC. In this case, the directories USER and MARY will be created at the receiving workstation if they do not already exist. NOTE: A fileset is always decompressed into the target directory that is specified when creating a package. In the above example, if the Create Directory Structure option is checked and the fileset is included in a package that has a default path of C:\SALES, then the INVOICE.DOC file will be decompressed into C:\SALES\USER\MARY. 10. To save the fileset contents, choose the Save button. The changes made to a fileset are only committed to upon choosing the Save button. The Updating Fileset dialog box displays while the fileset contents are being saved and compressed. If you attempt to close the Edit Filesets dialog box without saving, you are prompted to save the fileset changes. The fileset is created and added to the Filesets dialog box. 20.4 Managing Filesets This section describes the procedures for editing, renaming, copying and deleting filesets. 20.4.1 Editing Filesets Editing a fileset may become necessary in order to add or delete a file according to a change in a fileset's intent. NOTE: It is recommended that you temporarily deactivate any packages which use the fileset you intend to edit. Use the following procedure to edit the contents of a fileset. The procedure assumes that you have already chosen the Filesets command from the Tools menu to display the Filesets dialog box. 1. Select the fileset from the list of Filesets, and choose the Edit button. A fileset can also be selected for editing by double clicking on the fileset name in the Filesets dialog box. The Edit Fileset dialog box displays listing all files included in the fileset. For each file in the fileset, the following information displays: o File Name - the name of the file o Original Size - the file size before compression o Compressed Size - the file size after compression o Ratio - the compression ratio o Date - the file's creation date o Time - the file's creation time o Path - the file's path which displays only if the Include Path option is checked in the Add File dialog box. NOTE: Some files may show a 0% compression ratio. This occurs when the file is already compressed or when the file is very small. 2. To add a file to the fileset, choose the Add button. The Add File dialog box displays. Refer to the section above entitled "Creating Filesets" for detailed procedures on using this dialog box. 3. To delete a file from the fileset, highlight the file name and choose the Delete button. A prompt displays asking you to confirm the deletion. Choose the Yes button to continue with the delete action. If deleted, the file name is removed from the Edit Filesets dialog box. 4. To save the edited fileset contents, choose the Save button. The changes made to a fileset are only committed to upon choosing the Save button. The Updating Fileset dialog box displays while the fileset contents are being saved and compressed. If you attempt to close the Edit Filesets dialog box without saving, you are prompted to save the fileset changes. 20.4.2 Renaming Filesets Changing the name of an existing fileset renames all instances of the former fileset name. For example, the new fileset name is reflected in the Filesets dialog box as well as in any packages which include the fileset. Use the following procedure to rename a fileset. The procedure assumes that you have already chosen the Filesets command from the Tools menu to display the Filesets dialog box. NOTES: a - A fileset can be renamed even if it is part of an actively scheduled package. b - The name of the .SET file which is maintaining the compressed fileset and is stored in the fileset directory does not change. 1. To rename a fileset, select the fileset name from the list of Filesets, and choose the Rename button. The Rename Fileset dialog box displays prompting you to enter a new fileset name. 2. Enter the new fileset name, and choose the OK button. The new fileset name displays in the Filesets dialog box, and the old name is removed. All attributes of the old fileset are preserved in the renamed fileset (i.e., the fileset contents do not change). 20.4.3 Copying Filesets Use the following procedure to copy a fileset. The procedure assumes that you have already chosen the Filesets command from the Tools menu to display the Filesets dialog box. NOTE: A fileset can be copied even if the original fileset is part of an actively scheduled package. 1. To copy a fileset, select the fileset name from the list of Filesets, and choose the Copy button. The Copy Fileset dialog box displays prompting you to enter a name for the new fileset. 2. Enter the new fileset name, and choose the OK button. The new fileset name is added to the Filesets dialog box. The new fileset contents are identical to the original fileset contents. 20.4.4 Deleting Filesets Use the following procedure to delete a fileset. The procedure assumes that you have already chosen the Filesets command from the Distribution menu to display the Filesets dialog box. NOTE: A fileset that is part of a scheduled package cannot be deleted. 1. To delete a fileset, select the fileset from the list of Filesets, and choose the Delete button. A prompt displays asking you to confirm the deletion. 2. Choose the Yes button to delete the fileset. The fileset name is removed from the Filesets dialog box. 21.0 Scripts Chapter 20 discussed the creation and management of filesets. This chapter discusses the creation and management of scripts--a series of commands to be executed on a remote workstation. NOTE: This chapter pertains to BrightWorks. 21.1 Introduction A script is a series of commands to be executed on a remote workstation. Scripts must be written according to a defined syntax, and they must be compiled successfully to be included in a package. NOTES: a - The commands and instructions for using BrightWorks' software distribution scripting language are documented in Chapter 22 of this manual. b - BrightWorks is shipped with several script files that can be customized for your own use. Refer to section 21.4.5 entitled "Incorporating BrightWorks Scripts." 21.1.1 Script Features The ability to send scripts from a central location can be used to contribute to the consistency and standardization of LAN workstations. Scripts enable the LAN administrator to easily do the following: o update system executables and/or drivers (e.g., operating systems, network drivers) o update system files (e.g., AUTOEXEC.BAT, CONFIG.SYS, WIN.INI, network login script) o install software on a user's workstation A user can create a new script, as well as edit, compile, copy, rename and delete a script. The steps for each procedure are discussed in this chapter. 21.1.2 Access to Script Functions Script functions are accessed by choosing the Scripts command from the Tools menu. The Scripts window displays listing all available scripts. Script management is performed by either choosing the buttons in the Scripts window or by choosing the corresponding commands from the File menu. For example, when the Scripts window is active, a new script can be created either by choosing the New button in the Scripts window or by choosing the New Script command from the File menu. The Edit menu commands provide the standard Cut, Copy and Paste functionality for use during script editing. 21.1.3 What's in this Chapter The following chart describes the sections in this chapter: SECTION DESCRIPTION Creating Scripts Describes procedures for defining new scripts. Compiling Scripts Describes the procedures for compiling scripts. Managing Scripts Describes procedures for editing, renaming, copying and deleting scripts. 21.2 Creating Scripts A script is created by assigning both a script name and a file name to the new script. The script name is used for identification purposes within BrightWorks. For example, it is immediately obvious that the script named "Upgrade to Win 3.1" is responsible for upgrading the Windows software to version 3.1. The script file name identifies the ASCII text file containing the script commands. The script file name must be a valid DOS file name (e.g., 8 characters plus the 3 character extension). After assigning the script name and file name, an "empty" script is created. The empty script must be edited in order to add commands. Use the following procedure to create a new script. 1. Choose the Scripts command from the Tools menu. The Scripts window displays listing the names of all defined scripts. For each script, the last compilation date, the status and the file name also displays. 2. Choose the New button. The Open New Script dialog box displays prompting you to enter the name, file name and destination directory for the new script. 3. Enter the new script information, and choose the OK button. The script name can be up to 80 characters, and all typed characters are valid. The script file name must follow the standard DOS conventions. NOTES: a - It is recommended that .SCR be assigned as the extension for all script file names. A script file is a text file and can be edited with an external editor. b - The scripts must reside on a network drive to which all users who will receive the script have access Upon choosing OK, the message "This file does not exist. Create the file?" displays. Choose the Yes button to create the script file and display the Script Editor window. The script name being edited displays in the title bar of the Script Editor window. All commands that are included in this script are listed. (The list is empty for new scripts.) 4. Type the script commands. Script commands can be directly typed into the Script Editor window. Commands can also be selected from a list of commands by choosing the Functions button in the Script Editor window or the Paste Script Function command from the BrightWorks Edit menu (refer to the explanation below). The script compiler requires one command per line. No error checking is performed until the script is compiled. Optional comments can be placed in the script preceded by a semi-colon. These comments are ignored at compile time. For example: ;This is a comment. NOTE: The commands and rules for using the scripting language are documented in Chapter 22 of this manual, "Software Distribution Script Language." Standard editing functions are available from the Edit menu on the BrightWorks menu bar. The commands that are available from the Edit menu are as follows: o Undo - removes the last change made to the script. o Cut - copies a block of selected text to the clipboard and removes the text from the Script Editor window. o Copy - copies a block of selected text to the clipboard. o Paste - places the block of text from the clipboard into the Script Editor window at the current cursor location. o Paste Script Function - displays the Choose Script Function dialog box. This dialog box allows you to select a function (from a list of all script functions) to be placed in the script at the current cursor location. A function can be selected by either double clicking on the function name, or highlighting the name and choosing the OK button. Choosing the Help button displays help text for the highlighted function. o Find - searches the script for a user-specified text string. o Next - searches the script for the next occurrence of the user-specified text string. o Replace - searches the script for a user-specified text string and replaces the found text with another user-specified text string. o Fonts - enables you to select the font, style and size of the script type. NOTE: During script editing, the status bar in the BrightWorks application window indicates the current line and column position of the typing cursor. 5. To compile the script, choose the Compile button in the Script Editor window. Refer to the next section for details on compiling scripts. 6. To save the script contents, choose the Save button in the Script Editor window. The saved script contents are stored in ASCII text format. The script must be compiled to be used in a package. To compile the script, follow the procedure below entitled "Compiling Scripts." 7. Choose the Close button to close the Script Editor window. If you did not save the script changes as in Step #6 above, you are prompted to do so now. Choose the Yes button to save the script changes, or choose No to close the Script Editor without saving any changes. The new script is added to the Scripts window. The status of all uncompiled scripts is 'ASCII.' A script must be compiled to be used in a package. 21.3 Compiling Scripts The Status field in the Scripts window indicates the status of each script. Script status can be either ASCII or COMPILED. A script's status must be COMPILED to be used in a package for distribution. The commands and instructions for using the scripting language are documented in Chapter 22 of this manual, "Software Distribution Script Language." The compilation process checks the syntax and validity of the script's commands. Use the following procedure to compile a script. The procedure assumes that you have already chosen the Scripts command from the Tools menu to display the Scripts window. 1. To compile a script, select the script in the Scripts window and choose the Compile button. While a compile is in progress, the Compile Status dialog box displays. When the compile is complete, the Status field in the Compile Status dialog box indicates success or failure. If the compile fails, the Function field indicates the first function found which has invalid parameters. The Statistics area indicates the total number of lines in the script (Lines field) and the number of errors found (Errors field). 2. Choose the OK button to continue. If the script compile is successful, then choose the Close button in the Script Editor window to return to the Scripts window which shows the script's status as COMPILED. If the script compile fails, then the Compiler Messages dialog box displays listing the first script line which contains errors. 3. To correct a compiler error condition, double click on an error line in the Compiler Messages dialog box. The Script Editor window displays with the script that you are attempting to compile. The selected error line is automatically highlighted. 4. Correct all error conditions, and attempt to re-compile the script. Refer to Chapter 22 of this manual for details on the scripting rules and commands. After successful compilation of the script, the script can be used in a package. NOTE: If you edit a script that has already been compiled, the script must be successfully re-compiled in order to be used in a package. Refer to the "Last Comp" field in the Scripts window to discover the date on which the file was last compiled. 21.4 Managing Scripts 21.4.1 Editing Scripts Editing a script may be necessary under two circumstances: o Existing scripts might need to be edited in order to add or delete commands according to a change in a script's intent. o When a script compilation fails, the script must be edited to resolve the error(s). NOTE: It is recommended that you temporarily deactivate any packages which use the script you intend to edit. Use the following procedure to edit the contents of a script. The procedure assumes that you have already chosen the Scripts command from the Tools menu to display the Scripts window. 1. Select the script from the Scripts window, and choose the Edit button. A script can also be selected for edit by double clicking on the script name in the Scripts window. The Script Editor window displays. The script name being edited displays in the title bar of the Script Editor window. All commands that are included in this script are listed. 2. Edit the script commands. Script commands can be directly typed into the Script Editor window. Commands can also be selected from a list of commands by choosing the Functions button in the Script Editor window or the Paste Script Function command from the BrightWorks Edit menu. The script compiler requires one command per line. No error checking is performed until the script is compiled. NOTES: a - The commands and rules for using the scripting language are documented in Chapter 22 of this manual, "Software Distribution Script Language." b - During script editing, the status bar in the BrightWorks application window indicates the current line and column position of the typing cursor. 3. To compile the script, choose the Compile button in the Script Editor window. Refer to section 21.3 entitled "Compiling Scripts" for details on compiling scripts. 4. To save the edited script contents, choose the Save button in the Script Editor window. 5. Choose the Close button to close the Script Editor window. NOTE: If you edit a script that has already been compiled, the script must be successfully re-compiled in order to be used in a package. 21.4.2 Renaming Scripts Changing the name of an existing script renames all instances of the former script name. For example, the new script name will be reflected in the Scripts window as well as in any packages which include the script. Use the following procedure to rename a script. The procedure assumes that you have already chosen the Scripts command from the Tools menu to display the Scripts window. NOTE: A script can be renamed even if it is part of an actively scheduled package. 1. To rename a script, select the script name from the Scripts, and choose the Rename button. The Rename Script dialog box displays prompting you to enter a new script name. 2. Enter the new script name, and choose the OK button. The new script name displays in the Scripts window, and the old name is removed. All attributes of the old script are preserved in the renamed script (i.e., the script contents do not change). NOTE: The script rename procedure only changes the script name--the script file name does not change. 21.4.3 Copying Scripts Use the following procedure to copy a script. The procedure assumes that you have already chosen the Scripts command from the Tools menu to display the Scripts window. NOTE: A script can be copied even if the original script is part of an actively scheduled package. 1. To copy a script, select the script from the Scripts, and choose the Copy button. The Copy Script dialog box displays prompting you to specify a name, file name and destination directory for the new script. The script name can be up to 80 characters, and all typed characters are valid. The script file name must follow the standard DOS conventions and can reside in any directory. NOTE: It is recommended that .SCR be assigned as the extension for all script file names. 2. Enter the new script information, and choose the OK button. The new script name is added to the Scripts window. The new script is populated with the same commands as the original script. 21.4.4 Deleting Scripts Use the following procedure to delete a script. The procedure assumes that you have already chosen the Scripts command from the Tools menu to display the Scripts window. NOTE: A script that is part of a scheduled package cannot be deleted. 1. To delete a script, select the script from the Scripts, and choose the Delete button. A prompt displays asking you to confirm the deletion. 2. Choose the Yes button to delete the script. If deleted, the script name is removed from the Scripts window. NOTE: The delete action only deletes the script name from the Scripts window. The corresponding .SCR file is not deleted. Therefore, if a script name is inadvertently deleted, you can create a new script and assign the same script file name to retrieve the deleted script contents. 21.4.5 Incorporating BrightWorks Scripts BrightWorks is shipped with several pre-defined scripts that can be customized for use in your environment. Upon BrightWorks installation, the script files are copied into the BWORKS program directory. The table below lists the purpose of each script and indicates the script file name: PURPOSE FILE NAME Word for Windows Local Installation LOCAL.SCR Find and Delete a Program File FINDDEL.SCR AUTOEXEC.BAT Replacement AUTORLP.SCR AUTOEXEC.BAT Append AUTOAPP.SCR AUTOEXEC.BAT Modification AUTOMOD.SCR CONFIG.SYS Replacement CFGRPLMT.SCR CONFIG.SYS Append CFGAPP.SCR CONFIG.SYS Modification CFGMOD.SCR DOS Upgrade 3.X to 6.X DOS3TO6.SCR DOS Upgrade 4.X to 5.X DOS4TO5.SCR DOS Upgrade 5.X to 6.X DOS5TO6.SCR Novell NETX Update NETXUP.SCR Novell Wkst ODI/VLM/IPX Driver NETBAT.SCR Startup Batch File Update VLM Upgrade VLMUPGRD.SCR Send Text Message to Network Users TYPE.SCR Copy Files to Server CPFS.SCR Windows Network Installation WININST.SCR Windows Add Program Group ADDGROUP.SCR Windows Add Program Item ADDITEM.SCR Windows INI Replacement INIRPL.SCR Windows INI Append WINIAPPD.SCR Windows INI Modification WININIMD.SCR Windows Spooler Setting in INI WINSPOOL.SCR Install SMRAGENT.EXE AGENT.SCR Windows Wallpaper Update WALLPAPR.SCR CC:MAIL for Windows installation NETINS.SCR Use the following procedure to incorporate a pre-defined script into BrightWorks. 1. Choose the Scripts command from the Tools menu. The Scripts window displays. 2. Choose the New button. The Open New Script dialog box displays. 3. Enter a name for the script in the Script Name field. The script name can be up to 80 characters, and all typed characters are valid. The script name is used within BrightWorks to identify the script. For example, if you are incorporating the script which adds a group to the Program Manager desktop, then you might want to define the script name as ADD PROGRAM GROUP. 4. Select the script to be incorporated into BrightWorks. Select a script from the list of script file names. For example, if you want to incorporate and edit the script which adds a group to the Program Manager desktop, then you would select the ADDGROUP.SCR file. 5. Choose the OK button. The Script Editor window displays listing the commands for the chosen script. 6. Edit the script commands. The commands and rules for using the scripting language are documented in Chapter 22 of this manual, "Software Distribution Script Language." 7. Choose the Compile button in the Script Editor window to compile the script. Refer to section 21.3 entitled "Compiling Scripts" for details on compiling scripts. 8. Choose the Save button in the Script Editor window. The script contents are saved. 9. Choose the Close button to close the Script Editor window. The new script is added to the Scripts window. Note that a script must be compiled to be used in a package. 22.0 Software Distribution Script Language Chapter 21 discussed creating and managing scripts. This chapter lists the variables and rules for each function in the BrightWorks scripting language. NOTE: This chapter pertains to BrightWorks. 22.1 Introduction A script is a series of commands to be executed on a remote workstation. Scripts must be written according to a defined syntax, and they must be compiled successfully to be included in a package. The commands and instructions for using the BrightWorks software distribution scripting language are discussed in this chapter. The procedures for creating, compiling and managing scripts are discussed in the Chapter 21 entitled "Scripts." 22.1.1 What's in this Chapter The following chart describes the sections in this chapter: SECTION DESCRIPTION Notes on Syntax Discusses several items to note regarding the general format of the script language functions. Script Functions Discusses the type of functions available, and summarizes their parameters and purpose. DOS Functions Lists each DOS function, providing the following: the function parameters, a description, tips for using the function, its return values and an example for using the function in a script. Easy System File Functions Lists each Easy System File function, providing the same information as above. Windows System File Functions Lists each Windows System File function, providing the same information as above. Miscellaneous Functions Lists each Miscellaneous function, providing the same information as above. Rules and System Variables Lists the allowable values for each parameter, and defines the variable rules. DOS Error Codes Lists the DOS error codes that can be returned from the script functions. 22.2 Notes on Syntax The following items must be noted when writing scripts: o Only one command can be placed on a line. o The syntax for each command/function is as follows: FUNC_NAME [parameter1], [parameter2], ...[parameterN] o Unless otherwise noted, each function returns a 0 if it is successful (i.e., the system variable [retval] is set to 0). The action to be taken as a result of a script's return code is defined when the script is included in a package. These "Advanced Package Options" are discussed in Chapter 24. o Some functions take "optional" parameters. The administrator should decide whether or not to specify these parameters. If they are not specified, an empty or NULL value must be passed to the compiler to act as a placeholder. For example, the COPY function has the following parameters: COPY [path] [filewild] [path] {filewild} where the last parameter, {filewild}, is optional. The COPY command below provides an example for copying all .BAT files from the C: drive to the B: drive, using a placeholder to stand for the last {filewild} parameter: COPY "C:\" "*.BAT" "B:\" "" In this example, the files are not renamed and retain their original .BAT extensions. 22.3 Script Functions Each script "command" is treated as a "function" (e.g., a C function) that has two basic properties: o each command has 0 to 4 parameters that it will be passed o most commands have a return code As such, the script language supports user defined variables (of integer and string type), as well as "system" variables. When necessary, the functions also implement return values from the parameters that are passed. Each function has one or more parameters that can be passed. In the following discussions, the required parameters are surrounded by [ ], and the optional parameters are surrounded by { }. Each parameter is the name of a rule, whose allowable values are listed later in this chapter. 22.3.1 Type of Functions The script functions are divided into the four major categories summarized below: DOS Functions (section 22.4): FUNCTION REQUIRED PARAMETERS DESCRIPTION ATTRIB [path] [filewild] [attribute] Changes the attributes of a file or multiple files. COPY [path] [filewild] [path] Copies a file or files to {filewild} another directory and file name(s). DELETEDIR [path] [filename] {deleteopt} Deletes a directory. DELETEFILE [path] [filewild] Deletes a file or multiple files. FINDFILE [path] [filewild] [strvar] Finds a file. MDIR [path] [filename] Creates a directory. RENAME [path] [filewild] [path] Renames a source file(s). [filewild] UPGRADEOS [upgopt] Upgrades DOS version from 3.x-5.x to either 5.00 or 6.00. Easy System File Functions (section 22.5): FUNCTION REQUIRED PARAMETERS DESCRIPTION ADDDEVICE [strvalue1] [strvalue2] Adds a new DEVICE= line to a [addopt] system file. ADDLINE [strvalue1] [strvalue2] Adds a line of text to a [addopt] system file. ADDPATH [strvalue1] [strvalue2] Adds a sub-directory to a [strvalue3] [addopt] path environment variable. CFGGETVALUE [strvalue] [intvar] Gets a numeric variable from a system file. CFGSETVALUE [strvalue] [intvalue] Sets a numeric variable in a system file. CFGGETSTRING [strvalue] [strvar] Gets a string variable from a system file. CFGSETSTRING [strvalue1] [strvalue2] Sets a string variable in a system file. REPLACEKEY [strvalue1] [strvalue2] Replaces a key value in a [strvalue3] system file. REPLACELINE [strvalue1] [strvalue2] Replaces an existing line in a system file with a new line. REPLACELINE-ADD [strvalue1] [strvalue2] Replaces or adds an existing [addopt] line in a system file. SETSYSFILE [path] [filename] Sets a system file to be manipulated. Windows System File Functions (section 22.6): FUNCTION REQUIRED PARAMETERS DESCRIPTION ADDGROUP [strvalue] Creates a new Program Manager group. ADDITEM [strvalue1] [strvalue2] Adds a new item to a Program [pathfile] Manager group. GETINIINT [pathfile] [strvalue1] Gets a key value (integer) [strvalue2] [intvar] from an INI file, and places the result in a variable. GETINISTR [pathfile] [strvalue1] Gets a key value (string) [strvalue2] [strvar] from an INI file, and places the result in a variable. SCHEDULEWIN [path] [filename] [text] Schedules a file to be run the next time the user runs Windows. WRITEINIINT [pathfile] [strvalue1] Writes a key value (integer) [strvalue2] [intvalue] to an INI file WRITEINISTR [pathfile] [strvalue1] Writes a key value (string) [strvalue2] [strvalue3] to an INI file. Miscellaneous Functions (section 22.7): FUNCTION REQUIRED PARAMETERS DESCRIPTION APPENDPATH [strvar] [strvalue] Appends the contents of a string value to the end of a string variable; however, it first checks if the last character of a string variable is a "\". If it is not, APPENDPATH will append a "\" and a value to the variable. ASSIGN [intvar] [intvalue] Performs a basic integer assignment operation. DEFINE [text] [defineopt] Used to create user defined variables of a string or integer type. EXIT [intvalue] Ends the script. IF..THEN..ELSE [intvalue1] [condoper] Allows conditional processing [intvalue2] of functions. NUMTOSTR [strvar] [intvalue] Converts a numeric value to a string variable. PAUSE [text] Pauses execution of the script until the user presses a key. REBOOT Immediately reboots the user's PC. SHELL [pathfile] {text}{shellopt} Allows a user to execute an external DOS batch file or executable program. STRCAT [strvar] [strvalue] Appends the contents of a string value to the end of a string variable. STRCOMPARE [strvar] [strvalue] Does a byte for byte comparison of two strings. STRCOPY [strvar] [strvalue] Copies a value into a string, overwriting the previous contents of the string. WRITELN [strvalue] Writes a string value (e.g., write to screen). NOTE: In the actual script, parameters are separated by a space; do not type the brackets. 22.3.2 User-defined Variables User-defined variables are defined by using the DEFINE command (see Miscellaneous Functions) to create a string or integer user-defined variable name. User-defined variables must be defined before listing any script functions. Also, the appropriate type must be used when calling a function that allows user-defined variable names. The functions that allow user-defined variables, system variables and literal text use the phrases [strvar] or [intvar] in their parameter listings. Check the Rules discussion in section 22.7 entitled "Rules and System Variables" for further details. 22.4 DOS Functions The DOS function set is used for managing a machine's files and directories. For example, files can be searched for, copied, deleted, renamed and tagged with a specified attribute; directories can be created and deleted. Return values are generated when appropriate (unless otherwise noted, the functions return 0 if successful). Any applicable system variables are also noted. Most DOS functions return a DOS error code if unsuccessful. Refer to the table in section 22.8 entitled "DOS Error Codes" for a list of the DOS error codes that may be returned. NOTES: a - When an "explicit " is mentioned, it can take the form of D:\PATH (SERVER/VOLUME:\PATH is not currently supported). b - Some functions take optional "options." The administrator should decide whether or not to specify these options. c - In the following function specifications, parameters in quotes represent literal parameters; all other parameters represent rules. The rules are listed in section 22.7 entitled "Rules and System Variables." ATTRIB [path] [filewild] [attribute] Parameter Description and Notes [path] Source path to files. This path must exist. [filewild] The file name whose attributes are to be changed. May contain wildcards (? and *). [attribute] RO - Read only RW - Read/Write A - Set Archive bit SY - System file H - Hidden file SH - Shareable (network only) -A - Turn off archive attribute -SY - Turn off system attribute -H - Turn off hidden attribute -SH - Turn off shareable attribute (network only) Description - Changes the attributes of a file or multiple files. Tip - To remove the Read Only attribute, use the RW attribute. (There is no -RO attribute.) Return Values: [RETVAL] = 0 if successful [RETVAL] = -1 if the SH or -SH attributes are used and the drive letter specified in [PATH] is not a network drive [RETVAL] = -2 if the SH or -SH attributes are used and no drive letter is specified in [PATH] [RETVAL] = DOS error code in all other cases Example - Set the AUTOEXEC.BAT file on a user's boot drive to Read Only: ATTRIB [BOOT_ROOT] "AUTOEXEC.BAT" RO COPY [path] [filewild] [path] {filewild} Parameter Description and Notes [path] Source path of file to be copied. [filewild] Source file name to be copied. May contain standard DOS wild cards (? and *). [path] Destination path. {filewild} Optional destination file name. (If not specified, *.* is assumed.) May contain standard DOS wild cards (? and *). May be used to rename file(s) during file copy. If not used, the placeholder "" or NULL must be specified. Description - Copies a file or files to another directory and file name(s). Return Values: [RETVAL] = 0 if file(s) are copied correctly [RETVAL] = DOS error code if the function is unsuccessful Example - Copy the WIN.INI file from the Windows directory found at login to the local Windows directory. Two examples of this are: COPY [WINDIR] "WIN.INI" "C:\WINDOWS" "" or COPY [WINDIR] "WIN.INI" "C:\WINDOWS" NULL DELETEDIR [path] [filename] {deleteopt} Parameter Description and Notes [path] Source path to the directory to be deleted. This path must exist. [filename] Directory name to be deleted. {deleteopt} Optional delete option: ALL - causes DELETEDIR to delete the specified directory and everything under it, including any subdirectories, hidden, system and read only files. If not used, NULL must be specified. Description - Deletes a directory. Tip - Use the ALL delete option with caution since it can delete entire directory trees. Return Values: [RETVAL] = 0 if the directory is successfully deleted [RETVAL] = DOS error code if the function is unsuccessful Example - Delete the Windows directory found at login and all of its files and sub-directories: DELETEDIR [WINDIR] ALL DELETEFILE [path] [filewild] Parameter Description and Notes [path] Source path to the file(s) to be deleted. This path must exist. [filewild] File name(s) to be deleted. Wild cards may be specified (? and *) to delete multiple files. Description - Deletes a file or multiple files. Return Values: [RETVAL] = 0 if the file(s) are deleted [RETVAL] = DOS error code if the function is unsuccessful Example - Delete all .DOC files from the F:\UZR\JOHN sub-directory: DELETEFILE "F:\UZR\JOHN" "*.DOC" FINDFILE [path] [filewild] [strvar] Parameter Description and Notes [path] Source path in which to search for files. This path must exist. [filewild] The search criteria. May contain wildcards (? and *). [strvar] A string variable which contains the file name of the first file found. (Before being used as a parameter, this variable must be defined using the DEFINE function.) Description - Finds a file. Return Values: [RETVAL] = 0 and copies the name of the first file found into [STRVAL] if successful [RETVAL] = -1 and sets [STRVAL] to NULL if no files are found Example - Test for the presence of the NET.CFG file in the [NET.CFG] directory: DEFINE "Result" STRING FINDFILE [NETCFG] "NET.CFG" RESULT MDIR [path] [filename] Parameter Description and Notes [path] Path in which to create the new directory. This path must exist. [filename] Sub-directory to create. Wild cards may not be specified. Description - Creates a directory. Return Values: [RETVAL] = 0 if the directory is successfully created [RETVAL] = DOS error code if the function is unsuccessful Example - Create the JOHN sub-directory in the UZR directory: MDIR "F:\UZR" "JOHN" RENAME [path] [filewild] [path] [filewild] Parameter Description and Notes [path] Source path to files to be renamed. This path must exist. [filewild] Source file name to be renamed. May contain wildcards (? and *). [path] Destination path (can be different than [path] to enable moving files, but the drives must be the same). [filewild] New file name. May contain wildcards (? and *). If so, the standards used by the DOS REN command are followed. Description - Renames a source file(s). Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code in all other cases Example - Rename all .BAT files in the C:\ drive to .BAK: RENAME "C:\" "*.BAT" "C:\" "*.BAK" UPGRADEOS [upgopt] Parameter Description and Notes [upgopt] 5.00 - upgrade DOS version to 5.00 6.00 - upgrade DOS version to 6.00 Description - Upgrades DOS version from 3.x-5x to either 5.00 or 6.00. Tips: 1) In order for BrightWorks to have access to the upgraded DOS files, EQUIP must first be run on a machine that has the desired DOS files. For example, to upgrade a machine's DOS version to 6.00, EQUIP first must be executed on a machine that has DOS 6.00. By executing EQUIP from the same directory in which the BrightWorks software distribution update program (SDUPDATE.EXE) file is located, the DOS files become accessible by BrightWorks. Note also that the machine on which EQUIP is run must not contain any system that modifies the machine's boot record (e.g., OS/2, Windows NT). NOTE: Do not use this function on a workstation that has Windows NT installed in a dual boot configuration. It will cause the boot menu to be lost. The PC will boot DOS only. 2) The machine must be rebooted after the script is executed. Use the REBOOT function as the last script function. Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code in all other cases Example - Upgrade a user's DOS version to 5.00: UPGRADEOS 5.00 IF [RETVAL]=0 ... ; copy DOS files, edit CONFIG.SYS, etc. REBOOT ENDIF 22.5 Easy System File Functions The Easy System File functions allow for easy manipulation of basic system files, such as CONFIG.SYS, AUTOEXEC.BAT, NET.CFG, or a login script. (Use the Windows System File functions to edit .INI files.) Most Easy System File functions return a DOS error code if unsuccessful. Refer to the table in section 22.8 entitled "DOS Error Codes" for a list of the DOS error codes that may be returned. NOTE: Prior to using any of the functions in this category, you must call SETSYSFILE. Also, none of the functions will create a backup of the file that they are modifying; however, a file will not be modified if a function fails. It is your responsibility to backup any file as necessary. All of the Easy System File functions make use of a "key" value. This value is used to search the file to aid in determining where to make a modification. All key searches are case insensitive. If a key is found, its corresponding value is defined as the first non- whitespace (e.g. tab, cr/lf, =, etc.) group of characters after the found key value. For example, consider the following line: PATH=C:\DOS;C:\WINDOWS If "PATH" is specified as the key, then the corresponding value is "C:\DOS;C:\WINDOWS." However, consider the following line: STACKS 9,256 If "STACKS" is specified as the key, then the corresponding value is "9,256." As a result, an equal sign is not necessary to identify a value that you might want to edit. NOTE: In the following function specifications, parameters in quotes represent literal parameters; all other parameters represent rules. The rules are listed later in this chapter. ADDDEVICE [strvalue1] [strvalue2] [addopt] Parameter Description and Notes [strvalue1] The path and driver name (e.g. C:\WINDOWS\EMM386.EXE). [strvalue2] The key value to search for (e.g. HIMEM.SYS). [addopt] Where [strvalue1] is to be placed: either BEFORE or AFTER [strvalue2]. Description - Adds a new DEVICE= line to a system file (typically the DOS CONFIG.SYS). Tip - If [strvalue2] is a null string or the key is not found, ADDDEVICE will add [strvalue1] in the position of the file indicated by [addopt]. Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code in all other cases Example - Place "DEVICE=C:\WINDOWS\EMM386.EXE" after the "DEVICE=HIMEM.SYS" line in the CONFIG.SYS file: SETSYSFILE "C:\" "CONFIG.SYS" ADDDEVICE "C:\WINDOWS\EMM386.EXE" "HIMEM.SYS" AFTER ADDLINE [strvalue1] [strvalue2] [addopt] Parameter Description and Notes [strvalue1] The entire line of text you wish to add. [strvalue2] A reference key value to be positioned relative to [strvalue1]. This is a "keyword" that will be searched for in the file. Specify as much or as little as you like. When the first occurrence of the keyword in a line is found, that line is used as the reference. [addopt] Specify where [strvalue1] is to be placed: either BEFORE or AFTER [strvalue2]. Description - Adds a line of text to a system file. Tip - If [strvalue2] is a null string, ADDLINE will place [strvalue1] in the position of the file indicated by [addopt]. Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code in all other cases Example - Add a new line to the end of a user's CONFIG.SYS file: SETSYSFILE "C:\" "CONFIG.SYS" ADDLINE "THIS IS NEW.." "" AFTER NOTE: As in the example above, non-specified parameters (e.g., [strvalue2]) can be indicated by empty quotes. Entering NULL with no quotes is also acceptable. ADDPATH [strvalue1] [strvalue2] [strvalue3] [addopt] Parameter Description and Notes [strvalue1] The name of the path environment variable to edit (PATH for DOS, or DPATH for OS/2, or TEMP, etc). [strvalue2] The sub-directory to be added. [strvalue3] The sub-directory that [strvalue2] will be placed either before or after. [addopt] Specify where [strvalue2] is to be placed: either BEFORE or AFTER [strvalue3]. Description - Adds a sub-directory to a path environment variable. Tips: 1) If [strvalue3] is a null string, ADDPATH will place [strvalue2] in the position of the path statement indicated by [addopt] (i.e., the new path will be placed at the beginning or end of the path statement). 2) If the key specified in [strvalue1] is not found, then a new one is added, with a "SET" prepended. This allows for adding path like environment variables such as "SET TEMP=", and so on. 3) This function can also be used to edit other lines such as a TEMP environment variable, or any other line that does something like "SET envvar=d:\path." Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code in all other cases Example - Add the sub-directory WINDOWS to the path and place it before the DOS variable in the AUTOEXEC.BAT file: SETSYSFILE "C:\" "AUTOEXEC.BAT" ADDPATH "PATH" "C:\WINDOWS" "C:\DOS" BEFORE CFGGETVALUE [strvalue] [intvar] Parameter Description and Notes [strvalue] The variable to be retrieved. [intvar] An integer variable to hold the retrieved value. (Before being used as a parameter, this variable must be defined using the DEFINE function.) Description - Gets a numeric variable from a system file (e.g., FILES, BUFFERS, etc.). Tip - If the value of the key specified is non-numeric (e.g., the DOS=HIGH), CFGGETVALUE sets parameter 2 to 0, but does not return an error code. Use CFGGETSTRING to get a string value. Return Values: [RETVAL] = 0 if successful [RETVAL] = -2 if the key value could not be found [RETVAL] = DOS error code in all other cases Example - Place the value of the FILES= statement in the CONFIG.SYS file into a user defined variable called nRESULT (which must first be defined!): DEFINE "nRESULT" STRING SETSYSFILE "C:\" "CONFIG.SYS" CFGGETVALUE "FILES" nRESULT CFGSETVALUE [strvalue] [intvalue] Parameter Description and Notes [strvalue] The variable to be set. [intvalue] The integer value. Description - Sets a numeric variable in a system file (e.g., FILES, BUFFERS, etc.). Tip: Use ADDLINE to add a new statement if one does not exist. Return Values: [RETVAL] = 0 if successful [RETVAL] = -2 if the key value could not be found [RETVAL] = DOS error code in all other cases Example - Set the value of the FILES= statement in the CONFIG.SYS file to 50, provided a FILES= statement already exists in the file: SETSYSFILE "C:\" "CONFIG.SYS" CFGSETVALUE "FILES" 50 CFGGETSTRING [strvalue] [strvar] CFGSETSTRING [strvalue1] [strvalue2] These two functions act exactly the same as CFG???VALUE, except they deal with string values rather than integer values. An administrator might use this to check non-numeric variables (e.g., STACKS=9,256 is a non numeric value). Note that before using the [strvar] variable as a parameter, the variable must be defined using the DEFINE function. REPLACEKEY [strvalue1] [strvalue2] [strvalue3] Parameter Description and Notes [strvalue1] The line in the system file which contains the key value to be replaced. [strvalue2] The key value to be replaced. [strvalue3] The new value. Description - Similar to REPLACELINE; however, it replaces a key value rather than the entire line. Tip - If [strvalue3] is a null string, [strvalue2] will be removed. Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code in all other cases Example - Change the "40" to a "50" in the FILES= line in the CONFIG.SYS file: SETSYSFILE "C:\" "CONFIG.SYS" REPLACEKEY "FILES=40" "40" "50" REPLACELINE [strvalue1] [strvalue2] Parameter Description and Notes [strvalue1] The key value of the line you wish to replace, such as PATH, COMSPEC or DEVICE. [strvalue2] The new value of the entire line. Description - Replaces an existing line in a system file with a new line. Tips: 1) If [strvalue2] is a null string, then the line will be deleted. 2) If the key value exists more than one time in the file, only the first instance is modified. Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code in all other cases Example - Replace the existing COMSPEC line in the CONFIG.SYS file with a new line: SETSYSFILE "C:\" "CONFIG.SYS" REPLACELINE "COMSPEC" "SET COMSPEC=C:\DRDOS\COMMAND.COM" REPLACELINEADD [strvalue1] [strvalue2] [addopt] Parameter Description and Notes [strvalue1] The key value of the line you wish to replace, such as PATH, COMSPEC or DEVICE. [strvalue2] The new value of the entire line. [addopt] Where [strvalue1] is to be placed: either BEFORE or AFTER [strvalue2]. Description - Similar to REPLACELINE, this function replaces an existing line in a system file with a new line. However, if the key specified in [strvalue1] is not found, then the line specified in [strvalue2] is added to the file, at the beginning or end of the file depending on the position defined by [addopt]. Tip: If [strvalue1] is not found, then the line specified as [strvalue2] will be added to the file in the position defined by [addopt]. Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code in all other cases Example - Replace the existing NETX line with the new line C:\NET\VLM. If NETX is not found, then the line will be appended to the end of the file: SETSYSFILE "C:\" "NET.BAT" REPLACELINEADD "NETX" "C:\NET\VLM" AFTER SETSYSFILE [path] [filename] Parameter Description and Notes [path] The path to the file to be modified. [filename] The name of the file to be modified. Description - Sets a system file to be manipulated. Tips: 1) This function must be called prior to calling any of the functions in the Easy System File function category. It needs to be called only once, unless you change the file you are working on in the script. 2) Using [BOOT_ROOT] as the [path] parameter will always modify the file on the boot disk, regardless of whether or not the user is given the option to override the installation path (in the package definition). Use [TARGET] as the [path] parameter if the user is given the option to override the installation path. Return Values: [RETVAL] = 0 if file is found [RETVAL] = 2 if file is not found Example - Designate a user's CONFIG.SYS file as the file to be edited. Two examples of this are: SETSYSFILE "C:\" "CONFIG.SYS" or SETSYSFILE [BOOT_ROOT] "CONFIG.SYS" 22.6 Windows System File Functions The Windows System File functions provide the ability to edit INI files and create and manipulate Program Manager groups. NOTES: a - In the following function specifications, parameters in quotes represent literal parameters; all other parameters represent rules. The rules are listed in section 22.8 entitled "DOS Error Codes." b - Many of the Windows System File functions have a [pathfile] parameter which specifies the path name and file name to an INI file. If you do not specify a full path to the Windows directory, then the actions performed by these functions occur on the first instance of Windows found, as determined by the path statement of the receiving machine. If Windows is not found in the path, then the distribution update program will search for the INI file in [BOOT_ROOT]\WINDOWS. If Windows is still not found, the update program will then try [BOOT_ROOT]\WIN31. c - The functions ADDGROUP, ADDITEM, and SCHEDULEWIN use the WSDUPD.EXE update program which is copied into the local Windows directory each time these functions are used. The next time the user runs Windows, WSDUPD.EXE runs and executes the appropriate function(s). It then deletes WSDUPD.EXE and WSDUPD.INI. If a user has SHARE.EXE loaded, a "sharing violation" message will display when trying to delete WSDUPD.EXE. This message can be ignored. ADDGROUP [strvalue] Parameter Description and Notes [strvalue] The string which specifies the name of the Program Manager group to be added. Description - Creates a new Program Manager group. Tip: When the ADDGROUP script function is executed, the BrightWorks software distribution update program WSDUPD.EXE is automatically copied into the workstation's Windows directory. The WSDUPD.EXE command is also added to the "Load=" line in the WIN.INI file. The next time Windows is run at the workstation, the function is executed and WSDUPD.EXE is removed from the WIN.INI "Load=" line. Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code if unsuccessful. The function might fail if WSDUPD.EXE could not be copied into the Windows directory or if the WSDUPD.EXE control file (WSDUPD.INI) could not be created. Example - Create a Program Manager group named COMPANY: ADDGROUP "COMPANY" NOTE: This function can be used with any third party shell program which emulates the Program Manager DDE interface. ADDITEM [strvalue1] [strvalue2] [pathfile] Parameter Description and Notes [strvalue1] The group to which the item will be added. [strvalue2] The name of the new item. [pathfile] The .EXE file to be associated with the new item. Description - Adds a new item to a Program Manager group. Tip: When the ADDITEM script function is executed, the BrightWorks software distribution update program WSDUPD.EXE is automatically copied into the workstation's Windows directory. The WSDUPD.EXE command is also added to the "Load=" line in the WIN.INI file. The next time Windows is run at the workstation, the function is executed and WSDUPD.EXE is removed from the WIN.INI "Load=" line. Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code if unsuccessful. The function might fail if WSDUPD.EXE could not be copied into the Windows directory or if the WSDUPD.EXE control file (WSDUPD.INI) could not be created. Example - Create a Program Manager group named APPS, and then create a program icon within the new APPS group named EXCEL: ADDGROUP "APPS" ADDITEM "APPS" "EXCEL" "U:\MS\EXCEL\EXCEL.EXE" NOTE: This function can be used with any third party shell program which emulates the Program Manager DDE interface. Also note that the path specified will appear in the command line as well as the working directory. The above EXCEL example demonstrates this. GETINIINT [pathfile] [strvalue1] [strvalue2] [intvar] This function works in exactly the same way as GETINISTR (below) except it is used to retrieve integer values from INI files. GETINISTR [pathfile] [strvalue1] [strvalue2] [strvar] Parameter Description and Notes [pathfile] The path and file name of the INI file. [strvalue1] The section of the INI file in which the entry is located (e.g., [386Enh]). [strvalue2] The entry whose associated string is to be retrieved (e.g., keyboard.drv=, however, do not include the = sign!). [strvar] Variable in which to place the found string. (Before being used as a parameter, this variable must be defined using the DEFINE function.) Description - Gets a key value (string) from an INI file, and places the result in a variable. Tip - If [strvalue2] is a null string or the key is not found, ADDDEVICE will add [strvalue1] in the position of the file indicated by [addopt]. Return Values: [RETVAL] = 0 if successful [RETVAL] = -1 if the [strvalue2] section name does not exist [RETVAL] = -2 if the [strvalue3] key does not exist [RETVAL] = DOS error code in all other cases Example - Determine whether Windows version 3.1 is installed at a workstation by looking at the CONTROL.INI file: DEFINE "VER" STRING GETINISTR "C:\WIN\CONTROL.INI" "[INSTALLED]" "3.1" VER SCHEDULEWIN [path] [filename] [text] Parameter Description and Notes [path] The path to the file to be run. [filename] The file name to be run upon Windows execution. [text] Optional command line arguments for the file. Description - Schedules a file to be run the next time the user runs Windows. Tip - This function could be used to automate the installation of a Windows program if a macro playback utility is used. Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code if unsuccessful. The function might fail if WSDUPD.EXE could not be copied into the Windows directory or if the WSDUPD.EXE control file (WSDUPD.INI) could not be created. Example - Schedule the Notepad program to run the next time Windows is run, and also open the README.TXT notepad file: SCHEDULEWIN "C:\WINDOWS" "NOTEPAD.EXE" "README.TXT" WRITEINIINT [pathfile] [strvalue1] [strvalue2] [intvalue] This function works exactly like WRITEINISTR (below), except that it is used to write an integer value to an INI file. WRITEINISTR [pathfile] [strvalue1] [strvalue2] [strvalue3] Parameter Description and Notes [pathfile] The path and file name of the INI file. [strvalue1] The section in which [strvalue2] is located (e.g., [386Enh]). [strvalue2] The entry whose associated string is to be modified (e.g., keyboard.drv=, however, don't include the = sign!). [strvalue3] The string to be written to the INI file. Description - Gets a key value (string) from an INI file, and writes the result to the INI file. Tips: 1) If the section name specified in [strvalue1] is not found, then it will be added to the end of the INI file, with a new key=value added in that section. 2) If the [strvalue1] section is found but the key value specified in [strvalue2] is not found, the new key value is added directly after the section name [strvalue1]. Return Values: [RETVAL] = 0 if successful [RETVAL] = DOS error code in all other cases Example - Define a "medium priority" in the [SPOOLER] section of the WIN.INI file: WRITEINISTR "C:\WIN\WIN.INI" "[SPOOLER]" "PRIORITY" "MEDIUM" 22.7 Miscellaneous Functions The Miscellaneous Functions include basic functions for defining, assigning, copying, comparing and concatenating variables. NOTE: In the following function specifications, parameters in quotes represent literal parameters; all other parameters represent rules. The rules are listed in section 22.8 entitled "DOS Error Codes." APPENDPATH [strvar] [strvalue] Parameter Description and Notes [strvar] The variable to contain the appended string (i.e., destination). (Before being used as a parameter, this variable must be defined using the DEFINE function.) [strvalue] The string value to be appended (i.e., source). Description - Adds a file name to a path or builds a path. This function acts the same way as STRCAT, except that it will check if the last character of [strvar] is a "\". If it is not, APPENDPATH will append a "\" to [strvar], and then [strvalue] will be appended. This is very useful (and necessary!) in building paths. Return Value: [RETVAL] = 0 always Example - Define the variable named PATH to be a string-type. Copy the location of the network configuration files into the PATH variable and then append it to the C:\DRIVERS directory. DEFINE "PATH" STRING STRCOPY PATH [NETCFG] APPENDPATH "C:\DRIVERS" PATH ASSIGN [intvar] [intvalue] Parameter Description and Notes [intvar] The integer type variable name which will be assigned a value. (Before being used as a parameter, this variable must be defined using the DEFINE function.) [intvalue] The numeric value to be assigned to the integer type variable. Description - Performs a basic integer assignment operation (e.g., a = b). Return Value: [RETVAL] = 0 always Example - Define the variable "NUM" as an integer type, and later assign 33 to the variable NUM: DEFINE "NUM" INTEGER ASSIGN NUM 33 DEFINE [text] [defineopt] Parameter Description and Notes [text] The variable being defined. [defineopt] The type of variable being defined (e.g., STRING or INTEGER). Description - Used to create user defined variables of a string or integer type. This variable can then be used later in the script. Tips: 1) All DEFINE statements must be declared before any script command is executed. 2) If a STRING type variable is declared, the login module will allocate 255 bytes (= 255 characters) of memory for the string. If an INTEGER type variable is declared, the login module will allocate 4 bytes (C type long which equals to an approximately -2 billion to +2 billion size integer). Return Value: [RETVAL] = 0 always Example - Define the variable "ANSWER" as a string type. DEFINE "ANSWER" STRING EXIT [intvalue] Parameter Description and Notes [intvalue] An integer type variable. Description - Ends the script. Tips: 1) If [intvalue] is set to a non-zero value, then the login module will increment the error count by one for the upgrade package and note the log with the error number returned. 2) If the package has been defined to execute the script before decompressing the fileset, then the EXIT command will prevent the decompression of the fileset. (For more information on defining "Advanced Package Options," refer to the section later in this chapter.) Return Value: none Example - End the script if an obtained value is greater than 50: IF RESULT <= 50 CFGSETVALUE "FILES" 55 ELSE EXIT 1 ENDIF IF [intvalue1] [condoper] [intvalue2] ... {ELSE...} ENDIF Parameter Description and Notes [intvalue1] An integer type variable to be evaluated against [intvalue2]. [condoper] Valid conditional operators are: =, !=, <, >, <=, >= [intvalue2] An integer type variable to evaluate [intvalue1] against. Description - Allows conditional processing of functions. IF..THEN evaluates the conditional expression defined by [intvalue1] [condoper] [intvalue2]. If the condition evaluates to be TRUE, then all functions following THEN are executed until an ELSE or ENDIF is reached. If the condition evaluates to FALSE and ELSE is defined, then all functions following the ELSE are executed until an ENDIF is reached. Tip - IFs can be nested up to 50 levels deep. Return Value: none Example - Obtain the FILES= value from the CONFIG.SYS file. If the value is less than or equal to 50, then change the value to 55; otherwise, exit the script: DEFINE "RESULT" INTEGER SETSYSFILE "C:\" "CONFIG.SYS" CFGGETVALUE "FILES" RESULT IF RESULT <= 50 CFGSETVALUE "FILES" 55 ELSE EXIT 1 ENDIF NUMTOSTR [strvar] [intvalue] Parameter Description and Notes [strvar] The variable to contain the converted value. (Before being used as a parameter, this variable must be defined using the DEFINE function.) [intvalue] The numeric value to be converted. Description - Converts a numeric value to a string variable. Return Value: [RETVAL] = 0 always Example - Convert the number 100 to a string and store the value in the defined variable named ONEHUNDRED: DEFINE "ONEHUNDRED" STRING NUMTOSTR ONEHUNDRED 100 PAUSE [text] Parameter Description and Notes [text] The text to be displayed on the user's screen during the pause. (This can be NULL) Description - Pauses execution of the script until the user presses a key. Tip - If [text]1 is NULL, then the default message "Strike any key to continue" is displayed on the screen. Return Value = 0 always Example - Display the message "Pausing... press any key to continue" during script execution. PAUSE "PAUSING ... PRESS ANY KEY TO CONTINUE." REBOOT This function immediately reboots the user's PC. It does not accept any parameters and does not return any values. Before the reboot, the script file is closed, the log database is closed, and any necessary cleanup is performed. NOTES: a - The PC will not reboot if a fileset is to be executed after the script. b - The REBOOT function might not work if the workstation is not 100% PC compatible. SHELL [pathfile] {text} {shellopt} Parameter Description and Notes [pathfile] The path and file name to execute. {text} The file's optional command line arguments. (This can be NULL.) {shellopt} Optional argument which can only be either [KEEPPATH] or NULL. Description - Allows a user to execute an external DOS batch file, executable program, or DOS command. Tip - To execute the program or batch file in [pathfile] and change to the specified path, use the KEEPPATH option as the {shellopt} parameter. If you don't specify the KEEPPATH option, SHELL will try to use the path from which the SDUPDATE program was run. KEEPPATH allows you to temporarily switch to the path from where you want to run the program. Return Values: [RETVAL] = 0 if successful [RETVAL] = -1 if failed Example - Execute LIST.COM and load the contents of the README.TXT file. Temporarily make the current directory C:\PUB\LIST.COM. SHELL "C:\PUB\LIST.COM" "README.TXT" "" KEEPPATH STRCAT [strvar] [strvalue] Parameter Description and Notes [strvar] The variable to contain the concatenated string (i.e., destination). (Before being used as a parameter, this variable must be defined using the DEFINE function.) [strvalue] The string value to be appended (i.e., source). Description - Appends the contents of [strvalue] to the end of the string [strvar]. Tip - If the resulting text in [strvar] is longer than the space allowed (255 bytes), then it will be truncated and properly null terminated. Return Value: [RETVAL] = 0 always Example - Add the string "ADDTHIS" to a string variable named STRINGS1&2: DEFINE "STRINGS1&2" STRING STRCAT STRINGS1&2 "ADDTHIS" STRCOMPARE [strvar] [strvalue] Parameter Description and Notes [strvar] The variable to be compared. (Before being used as a parameter, this variable must be defined using the DEFINE function.) [strvalue] The value to compare the variable against. Description - Does a byte for byte comparison of two strings. Return Values: [RETVAL] = 0 if the strings are identical [RETVAL] = < 0 if [strvar] is less than [strvalue] [RETVAL] = > 0 if [strvar] is greater than [strvalue] Example - Check the current NetWare login name against a specified login name ("Supervisor"). DEFINE "NAME" STRING STRCOPY NAME [LOGINNAME] STRCOMPARE NAME "SUPERVISOR" STRCOPY [strvar] [strvalue] Parameter Description and Notes [strvar] The variable to receive the copied string value (i.e., destination). (Before being used as a parameter, this variable must be defined using the DEFINE function.) [strvalue] The string value to be copied (i.e., source). Description - Copies a value into a string, overwriting the previous contents of the string. Return Value: [RETVAL] = 0 always Example - Copy the string "ABC" into the string variable named "HOLDABC": DEFINE "HOLDABC" STRING STRCOPY HOLDABC "ABC" WRITELN [strvalue] Parameter Description and Notes [strvalue] The string to display on screen. Description - Writes the [strvalue] line to stdout (e.g., the screen). This might be useful for displaying error messages, etc. Return Value: [RETVAL] = 0 always Example - Define the variable named RESULT. Place the value of the FILES= statement in the CONFIG.SYS file into RESULT, and then write the value of RESULT. DEFINE "VALUE" STRING DEFINE "RESULT" INTEGER SETSYSFILE "C:\" "CONFIG.SYS" CFGGETVALUE "FILES" RESULT NUMTOSTR VALUE RESULT WRITELN VALUE 22.8 Rules and System Variables Most of the functions in the BrightWorks script language have parameters that are specified or passed to them. The valid entries for each parameter type are called rules. For example, the UPGRADEOS function has one parameter named [upgopt]. As indicated in the table below, the value of the [upgopt] parameter can be either 5.00 or 6.00. Therefore, the allowable values for the [upgopt] parameter are 5.00 and 6.00. NOTE: When a user defined variable of string type is expected, [STRVAR] is the rule. When a user defined variable of integer type is expected, [INTVAR] is the rule. The table below lists the rules (allowable values) for each parameter. Rule Name Allowed Values ADDOPT BEFORE AFTER ATTRIBUTE RO RW A SY H SH -A -SY -H -SH CONDOPER < > = != >= <= DEFINEOPT STRING INTEGER DELETEOPT ALL FILENAME [STRVAR] "filename.ext" (wild cards not allowed for file name) FILEWILD [STRVAR] "filename.ext" "*.*" (wild cards are allowed but not required for a file name) INTVALUE [INTVAR] [RETVAL] # (where # is a valid integer) INTVAR [INTVAR] PATH [STRVAR] "path" [TARGET] [BOOT_ROOT] [WINDIR] [WINSYSDIR] [NETCFG] [HDRIVE] [NDRIVE] [SERVERNAME] [LOGINNAME] [FUSIONNAME] [LOGSCRNAME] PATHFILE [STRVAR] "{path\}filename.ext" SHELLOPT KEEPPATH STRVAR [STRVAR] STRVALUE [STRVAR] "text" [TARGET] [BOOT_ROOT] [WINDIR] [WINSYSDIR] [NETCFG] [HDRIVE] [NDRIVE] [SERVERNAME] [LOGINNAME] [FUSIONNAME] [LOGSCRNAME] TEXT "text" UPGOPT 5.00 6.00 22.8.1 System Variables The rules listed in the above table are defined as follows: 22.8.2 String Type Rules: [BOOT_ROOT] - the root of the boot drive of the workstation on which the script is executed [HDRIVE] - drive letter of the first available hard drive (may be boot or network drive) [FUSIONNAME] - primary user name from BrightWorks databases (generally same as LOGINNAME) [LOCATION] - location field from BrightWorks inventory databases [LOGINNAME] - login name of user [LOGSCRNAME] - full path and file name of login script for user running update. [NDRIVE] - drive letter of the first available network drive [NETCFG] - path to NET.CFG used at NetWare shell load (must be in path) [SERVERNAME] - name of server on which the update program is running [TARGET] - installation path as defined by the administrator (or changed by user, if able to) [WINDIR] - the user's Windows directory (directory in which the login module finds WIN.INI - this directory must be in the path) [WINSYSDIR] - the user's Windows\System directory (directory in which the login module finds USER.EXE - this directory may be in the SYSTEM directory below WINDIR, or in the path) 22.8.3 Integer Type Rules: [DISKSPACE] - available disk space in drive specified in [TARGETDIR]. The number is in bytes. [RETVAL] - return code of last command completed 22.9 DOS Error Codes The following lists the DOS error codes that may be returned from the script functions. For each error, the number, message, reason, action, and functions that return the error are described. o Message # 2 - "File not found." Reason: file specified in the script does not exist. Check the filename and path. Functions returning error: GETINISTR() - The file from which you requested a string does not exist. GETINIINT() - The file from which you requested an integer does not exist. o Message # 3 - "Path not found." Reason: a directory path specified in the script does not exist. Check the path and directory name. Functions returning error: DELETEDIR() - The directory that you requested to delete does not exist, or it does not exist in the location you specified. o Message # 4 - "Too many open files (no handles left)." Reason: insufficient file handles are specified in CONFIG.SYS. Increase the number of file handles in CONFIG.SYS. Functions returning error: COPY() All Easy System File and Windows System File functions. o Message # 5 - "Access denied." Reasons: specified drive or file cannot be accessed. Insufficient user rights, read only files, disk full. Verify the user rights, file attributes and available disk space. Functions returning error: DELETEFILE(), ADDPATH(), ADDLINE(), REPLACELINE(), REPLACEKEY(), ADDDEVICE(), CFGSETVALUE(), CFGSETSTRING(), REPLACELINEADD(), WRITEINISTR(), WRITEINIINT() - Is the file flagged read only? Is the disk full? Does the end user have insufficient rights in the specified directory? DELETEDIR() - Subdirectories and/or files exist, and the "ALL" option was not used in the script. ADDGROUP(), ADDITEM(), SCHEDULEWIN() - Is WIN.INI flagged read only? o Message # 8 - "Insufficient memory" Reason: Not enough memory to complete the specified action. Unload unnecessary TSRs, check workstation memory management. Functions returning this error: All DOS, Easy System File and Windows System File functions. o Message # 15 - "Invalid drive" Reason: The drive specified does not exist. Check the drives specified in the script. Functions returning this error: All DOS, Easy System File and Windows System File functions. o Message # 16 - "Attempt to remove current directory" Reason: The directory you attempted to delete is active on a drive. Functions returning this error: DELETEDIR() - Is the directory specified active on the drive? If it is a network drive, are other users active on the drive? o Message # 17 - "Not same device" Reason: An action was specified on two separate drives. Ensure that you are not attempting to "cross drives" on an action that does not permit this (e.g., RENAME) Functions returning this error: RENAME() - Are the source and target locations different? o Message # 18 - "No more files" Reason: The specified file could not be found. Check the path and filename. Check end user rights in the directory specified. Functions returning this error: DELFILE(), ATTRIB(), RENAME(), SETSYSFILE(), COPY() - Does the specified file exist in the location specified? Does the end user have sufficient rights to see the file? o Message # 19 - "Disk is write protected" Reason: The write protect tab is enabled on the disk specified in the operation. Remove the write protect tab. Functions returning this error: All DOS, Easy System File and Windows System File functions. o Message # 21 - "Drive not ready" Reason: There is no disk in the drive specified in the operation. Insert the diskette. Functions returning this error: All DOS, Easy System File and Windows System File functions. o Message # 22 - "Invalid disk command" Reason: Media access error. Check the diskette or drive. Functions returning this error: Bad or damaged diskette. o Message # 23 - "CRC error" Reason: Media access error. Check the diskette or drive. Functions returning this error: Bad or damaged diskette. o Message # 24 - "Invalid length" Reason: Media access error. Check the diskette or drive. Functions returning this error: Bad or damaged diskette. o Message # 25 - "Seek error" Reason: Media access error. Check the diskette or drive. Functions returning this error: Bad or damaged diskette. o Message # 27 - "Sector not found" Reason: Media access error. Check the diskette or drive. Functions returning this error: Bad or damaged diskette. o Message # 29 - "Write fault" Reason: Media access error. Check the diskette or drive. Functions returning this error: Bad or damaged diskette. o Message # 30 - "Read fault" Reason: Media access error. Check the diskette or drive. Functions returning this error: Bad or damaged diskette. o Message # 31 - "General failure" Reason: Media access error. Check the diskette or drive. Functions returning this error: Diskette may not be formatted. 23.0 Scopes Chapter 22 discussed the software distribution script language This chapter discusses the creation and management of scopes--the group of workstations defined to receive a distributed package. NOTE: This chapter pertains to BrightWorks. 23.1 Introduction A scope is a group of workstations defined to receive a distributed package. Defining a scope is as easy as assigning a name to the new scope. After the scope is created, any number of workstations can be included in the scope definition. 23.1.1 Scope Features By taking advantage of the database of inventory information maintained by BrightWorks, users can create scopes by selecting from nodes that match specific filtering criteria. The filtering criteria is saved as a "query" and then applied against the database to narrow down the list of applicable workstations. Scope membership is subsequently assigned using the list of nodes that match the user-specified filtering criteria. Items such as CPU speed, workstation memory and installed software can be used to accommodate a scope's intent. For example, a scope named CPU386 might consist of the network's 386 workstations; a scope named 386>16MHz might consist of the network's 386 workstations that also have a CPU clock frequency greater than 16 MHz. Scopes and queries can be stored, used and reused as resources within BrightWorks. A user can create a new scope, as well as edit, copy, rename and delete a scope. The steps for managing both scopes and queries are provided in this chapter. 23.1.2 Access to Scope Functions Scope functions are accessed by choosing the Scopes command from the Tools menu. The Scopes dialog box displays listing all available scopes. 23.1.3 What's in this Chapter The following chart describes the sections in this chapter: SECTION DESCRIPTION Creating Scopes Describes procedures for defining new scopes. Scope Queries Describes procedures for applying queries to scopes, removing queries from scopes, creating new queries, editing queries and deleting queries. Managing Scopes Describes procedures for editing, renaming, copying and deleting scopes. 23.2 Creating Scopes Use the following procedure to create a new scope. NOTE: At least one audit must have been run in order to create a scope. 1. Choose the Scopes command from the Tools menu. The Scopes dialog box displays listing the names of all defined scopes. 2. Choose the New button. The New Scope dialog box displays prompting you to enter a name for the new scope. 3. Enter the new scope name, and choose the OK button. A scope name can be up to 80 characters, and all typed characters are valid. For example, enter the new scope name "386/16MHZ" which will include the network's 386/16MHz nodes. Upon choosing the OK button, the Edit Scope dialog box displays prompting you to define the new scope. The Edit Scope dialog box consists of two lists: o Nodes in SITE - the list on the left side of the dialog box consists of all node names that apply to the local site. The site name is indicated by the SITE text in the list title. The nodes in this list are not included in the selected scope (i.e., the list to the right). o Nodes included in Scope - the list on the right side of the dialog box consists of the nodes that are in the selected scope. NOTE: The Query Options section of the Edit Scope dialog box is used to perform a query to filter the node names in the Nodes in SITE list. For detailed instructions on performing queries, refer to the next section of this chapter entitled "Scope Queries." 4. Define the nodes to be included in the scope. Use the push buttons in the center of the Edit Scope dialog box to define the scope members. To define scope membership, select a node name from either list and choose the appropriate button: o Include >> - choose this button to include the selected node in the scope. The node name moves from the left list to the right list. o Include All - choose this button to include all listed nodes in the scope. All node names move from the left list to the right list. o << Remove - choose this button to remove the selected node from the scope. The node name moves from the right list to the left list. o Remove All - choose this button to remove all nodes from the scope. All node names move from the right list to the left list. NOTE: Because user names can be edited via the View Inventory Details dialog box, the node names in the Nodes in SITE list do not necessarily correspond to NetWare user names. As a result, there may be duplicate names in this list. Viewing the inventory details of nodes with the same name enables you to differentiate between the nodes. Choose the View button or double click on a name in either list to invoke the View Inventory Details dialog box for the selected node. 5. When the scope members are defined, choose the Save button. 23.3 Scope Queries When no filtering criteria is applied to a scope, all nodes in the local BrightWorks site are listed in the Nodes in SITE list of the Edit Scope dialog box. This condition is indicated by the entry in the Last Query field. Searching through a large list of nodes might make the process of defining scope membership cumbersome. Applying a query to a scope refines the number of nodes in the Nodes in SITE list so that scope membership can be made from a "qualified" list of nodes. NOTE: Only one query can be applied to a scope at any time. Each query can consist of more than one filtering criteria. An applied query always filters from the entire list of nodes in the local BrightWorks site. Queries can be saved and applied to any number of scopes. The same queries can be applied to BrightWorks inventory and distribution reports, as is discussed in Chapter 18 of this manual. This section lists the procedures for: o Creating a new query o Editing a query o Deleting a query o Applying a query to the scope o Removing a query from the scope 23.3.1 Creating a New Query Use the following procedure to create a new query. The procedure assumes that you have already chosen the Select button in the Edit Scope dialog box to display the Select Query dialog box. NOTE: All queries are also available when generating BrightWorks inventory and distribution reports, as discussed in Part Three, Chapter 18 of this manual. 1. Choose the Add button in the Select Query dialog box. The Add Query dialog box displays. Press the key to move from field to field within this dialog box. 2. Enter a Query Name and define a filter entry. The purpose of each filter entry is to narrow down the list of nodes that apply to the specified criteria. If more than one filter entry is defined, the entries are "linked" using either the AND or OR relationship. For example, assume the following two filter entries: Central Processing Unit = Intel_80386 CPU Clock Frequency > 66.00 Mhz If the entries are linked with the OR relationship, only the nodes that satisfy either criteria (i.e., all Intel 80386 machines and all machines that have a clock speed greater than 66 Mhz) are included in the database sort. If the entries are linked with the OR relationship, the nodes that satisfy either criteria (i.e., all 286 machines and all machines that have a 720k floppy drive) are included in the database sort. For each filter entry, specify the following: o Query Name - Enter a query name up to 80 characters in length. o Component - Choose a component from the BrightWorks inventory database to use as the filter basis. Select a component from the drop-down list associated with this field (e.g., Brand, Computer Model, CPU Clock Frequency). o Condition - Choose a conditional operator from the drop-down list associated with this field (e.g., equal to, less than, greater than, not equal to). 'Equal to' is the default condition. o Description - If desired, choose a description of the component. The items which automatically display in this list depend on the selected component. For example, "Intel_80386" might display if Central Processing Unit is entered in the Component field; "16.00 Mhz" might display if CPU Clock Frequency is entered in the Component field. See Note (a) below. o Query Link - Specify the relationship between the filter entries (e.g., Central Processing Unit = 80386 OR Central Processing Unit = 80486). The link options are AND and OR. See Note (b) below. NOTES: a - To create a query which tests for the presence of a component, leave the Description field blank. For example, to include all nodes with a hard disk, construct a query with the following entries: Component = Hard Disk #1 < > In this case, the Component description is left blank, and the query results in including all nodes which have a hard disk (i.e., Hard Disk #1 does not equal blank). b - All filter entries in a query must have the same Query Link type (e.g., all entries will be linked by AND or all entries will be linked by OR). 3. Choose the Insert button to accept the filter entry definition. The entry is added to the Current Query List in the Edit Query dialog box. 4. If required, insert additional filter entries. Repeat steps #2 and #3 above. NOTE: To add a filter entry between existing entries, first highlight the filter entry line in the Current Query list where you want the new entry to be placed. The new defined entry is placed in the highlighted position. 5. When all filter entries are defined, choose the Save button. The query is saved and added to the Available Queries list in the Select Query dialog box. The new query can now be applied to a scope. 23.3.2 Editing a Query Use the following procedure to edit the definition of an existing query. The procedure assumes that you have already chosen the Select button in the Edit Scope dialog box to display the Select Query dialog box. 1. Select a query from the Select Query dialog box, and choose the Edit button. The Edit Query dialog box displays showing the defined filter entries for the query. 2. Modify the filter information, and choose the Save button. To delete a filter entry, highlight the entry in the Current Query List and choose the Delete button. To add a filter entry, specify the Component, Condition and Description, and choose the Insert button. (For detailed instructions on adding filter entries, refer to the procedure above entitled "Creating a New Query.") NOTE: New filter entries are appended to the end of the Current Query List unless a filter entry is selected. If an existing filter entry is selected, then the new filter entry gets inserted above it when you choose the Insert button. 23.3.3 Deleting a Query Use the following procedure to delete an existing query. The procedure assumes that you have already chosen the Select button in the Edit Scope dialog box to display the Select Query dialog box. 1. Select the query to be deleted from the Select Query dialog box, and choose the Delete button. A prompt displays asking you to confirm the deletion. 2. Choose the Yes button to delete the query. If deleted, the query name is removed from the Available Queries list. NOTE: Queries that are currently applied to a scope and/or BrightWorks inventory and distribution report can be deleted. 23.3.4 Applying a Query to the Scope Use the following procedure to apply an existing query to a scope. The procedure assumes that you have already chosen the Edit button in the Scopes dialog box to display the Edit Scope dialog box. 1. Choose the Select button in the Query Options section of the Edit Scope dialog box. The Select Query dialog box displays listing all defined queries. 2. Select the query name from the Available Queries list, and choose the Apply button. To select a query name, point to the query and click the left mouse button. NOTE: Applying a query to a scope causes a Printing Status dialog box to display while the database records are being sorted. When this occurs, nodes are being selected (i.e., the information is not being sent to the printer). The Select Query dialog box closes, and the selected query name is placed into the Last Query field of the Edit Scope dialog box. The BrightWorks database records are sorted, and only the records that match the query's specified filter criteria will display in the Nodes in SITE list. Now you can assign scope members using a "qualified" list of nodes. NOTE: If you already selected nodes to be included in the scope (i.e., the nodes listed in the Nodes Included in Scope list), the nodes continue to be "included" even if they do not match the filter criteria. 23.3.5 Removing a Query from the Scope Use the following procedure to remove a scope query. 1. Choose the Select button in the Query Options section of the Edit Scope dialog box. The Select Query dialog box displays. 2. Select the query name, and choose the Apply button. The Select Query dialog box closes. All nodes in the local BrightWorks site are listed in the Nodes in SITE list of the Edit Scope dialog box. 23.3.6 Creating a Complex Query A query can consist of any number of filter entries that are defined to produce a desired result. The relationship between the filter entries is referred to as the "link." Assume that you are responsible for upgrading the workstations of all network users in the Sales Department who are currently using Intel 286 machines with a CPU speed less than 16 MHz and which have a 1.44 megabyte floppy disk designated as drive A:. Use the following procedure to create a query that defines the scope of users in the above example. 1. In the Add Query dialog box, enter a Query Name. Enter a name that uniquely identifies this query (e.g., "Sales 286/16Mhz"). 2. Define the first filter entry, and choose the Insert button. Enter the following for each field: Component: Department Condition: = Description: Sales Query Link: AND 3. Define the second filter entry, and choose the Insert button. Enter the following for each field: Component: Central Processing Unit Condition: = Description: Intel_80286 Query Link: AND 4. Define the third filter entry, and choose the Insert button. Enter the following for each field: Component: CPU Clock Frequency Condition: < Description: 16MHz Query Link: AND 5. Define the fourth filter entry, and choose the Insert button. Enter the following for each field: Component: Floppy Disk #1 Condition: = Description: A: 1.44 M Query Link: AND 6. Choose the Save button to save the query. The filter entries in the Current Query list in the Edit Query dialog box should be identical to the following: Department = Sales Central Processing Unit = Intel_80286 AND CPU Clock Frequency < 16MHz AND Floppy Disk #1 = A: 1.44 M AND 23.4 Managing Scopes 23.4.1 Editing Scopes Editing a scope may become necessary under two circumstances: o Existing scopes might need to be edited in order to add or delete members according to a change in a scope's intent. o Scopes that are attached to packages might need to be edited when re-sending packages. Scope members are the nodes that are defined as a group to receive a distributed package. NOTE: An existing scope can be edited even if the scope is part of a scheduled package. This is useful if you need to re-send a package to a node(s). If new nodes are added to a scope that is included in an active package, then the package will automatically get distributed to the new nodes. Use the following procedure to edit a scope. The procedure assumes that you have already chosen the Scopes command from the Tools menu to display the Scopes dialog box. 1. Select the scope from the list of Scopes, and choose the Edit button. A scope can also be selected for editing by double clicking on the scope name in the Scopes dialog box. The Edit Scope dialog box displays. The Edit Scope dialog box consists of two lists: o Nodes in SITE - the list on the left side of the dialog box consists of all node names that apply to the local site. The site name is indicated by the SITE text in the list title. The nodes in this list are not included in the selected scope (i.e., the list to the right). o Nodes included in Scope - the list on the right side of the dialog box consists of the nodes that are in the selected scope. NOTE: The Query Options section of the Edit Scope dialog box is used to perform a query to filter the node names in the Nodes in SITE list. for detailed instructions on performing queries, refer to section 23.3 entitled "Scope Queries." 2. Define the nodes to be included in the scope. Use the push buttons in the center of the Edit Scope dialog box to define the scope members. To define scope membership, select a node name from either list and choose the appropriate button: o Include >> - choose this button to include the selected node in the scope. The node name moves from the left list to the right list. o Include All - choose this button to include all listed nodes in the scope. All node names move from the left list to the right list. o << Remove - choose this button to remove the selected node from the scope. The node name moves from the right list to the left list. o Remove All - choose this button to remove all nodes from the scope. All node names move from the right list to the left list. NOTE: Because user names can be edited via the View Inventory Details dialog box, the node names in the Nodes in SITE list do not necessarily correspond to NetWare user names. As a result, there may be duplicate names in this list. Viewing the inventory details of nodes with the same name enables you to differentiate between the nodes. Choose the View button or double click on a name in either list to invoke the View Inventory Details dialog box for the selected node. 3. When the scope members are defined, choose the Save button. 23.4.1 Renaming Scopes Use the following procedure to rename a scope. The procedure assumes that you have already chosen the Scopes command from the Tools menu to display the Scopes dialog box. NOTE: A scope can be renamed even if it is part of an actively scheduled package. 1. To rename a scope, select the scope from the list of Scopes, and choose the Rename button. The Rename Scope dialog box displays prompting you to enter a new scope name. 2. Enter the new scope name, and choose the OK button. The new scope name displays in the Scopes dialog box, and the old name is removed. All attributes of the old scope are preserved in the renamed scope (i.e., the scope members do not change). 23.4.2 Copying Scopes Use the following procedure to copy a scope. The procedure assumes that you have already chosen the Scopes command from the Tools menu to display the Scopes dialog box. NOTE: A scope can be copied even if the original scope is part of an actively scheduled package. 1. To copy a scope, select the scope from the list of Scopes, and choose the Copy button. The Copy Scope dialog box displays prompting you to enter a name for the new scope. 2. Enter the new scope name, and choose the OK button. The new scope name is added to the Scopes dialog box. The new scope members are identical to the original scope members. 23.4.3 Deleting Scopes Use the following procedure to delete a scope. The procedure assumes that you have already chosen the Scopes command from the Tools menu to display the Scopes dialog box. NOTE: A scope that is part of a scheduled package cannot be deleted. 1. To delete a scope, select the scope from the list of Scopes, and choose the Delete button. A prompt displays asking you to confirm the deletion. 2. Choose the Yes button to delete the scope. If deleted, the scope name is removed from the Scopes dialog box. 24.0 Packages Chapter 23 discussed the creation and management of scopes. This chapter discusses the creation and management of packages--the method by which software is distributed across your network. NOTE: This chapter pertains to BrightWorks. 24.1 Introduction Creating and activating a package is the method by which software is distributed across your local area network. When a package is created, it is assigned a scope and a "Start Date." Upon reaching the start date and running the SDUPDATE.EXE program at a workstation in the scope, an active package automatically gets sent to the workstation. A package also consists of a fileset and/or a script to be distributed to the group of remote workstations. For example, a package named UPGRADE_DOS might include a scope of users running DOS 3.3. The package might also include a script which installs a fileset consisting of the DOS 6.0 files. The software distribution update program (SDUPDATE.EXE) is integrated with the packaging functionality. The update program is responsible for determining the conditions for accepting or rejecting a package. The program is also responsible for reporting on package status as input to the Packages window and the Software Distribution Log. 24.1.1 Package Features In addition to the contents and scope, every package is assigned a schedule and a method for delivery. A package's schedule is the date on which the package is to be distributed. The method of delivery specifies instructions for the receiving workstation. There are several options available to the workstation user when a package is received. For example, package ABC might be configured to prompt the user five times to accept the package before proceeding with the installation of its fileset. A user can create a new package, as well as edit, rename and delete a package. The steps for each procedure are discussed in this chapter. 24.1.2 Access to Package Functions Most package functions are accessed by either: o choosing the Packages command from the Tools menu, or o choosing the Distribute tool bar button Both of the above actions cause the Packages window to display. Package management is performed by either choosing the buttons in the Packages window or by choosing the corresponding commands from the File menu. For example, when the Packages window is active, a new package can be created either by choosing the New button in the Packages window or by choosing the New Package command from the File menu. The information in the Packages window is updated according to an interval called the "package timer." Package timer functions are accessed by choosing the Distribution command from the Administration menu. 24.1.3 What's in this Chapter The following chart describes the sections in this chapter: SECTION DESCRIPTION Creating and Editing Packages Describes procedures for defining new packages and for editing existing packages. Managing Packages Describes procedures for renaming, activating/deactivating, and deleting packages. The Package Timer Describes procedures for setting the package timer interval. 24.2 Creating and Editing Packages Use the following procedure to create a new package. 1. Choose the Packages command from the Tools menu, or choose the Distribute tool bar button. The Packages window displays. This window lists the names of all defined packages. For each package, the following is indicated: o Start Date - the date the package will be distributed o Status - the package's status (Active or Inactive) o Total - the total number of workstation in the package's scope o Done - the number of successful updates so far o Errors - the total number of failed attempts at performing an update NOTE: Packages that have the same Start Date are distributed in the order in which they appear in the Packages window. To change a package's priority, refer to section 24.3.1 entitled "Prioritizing Packages." 2. Choose the New button in the Packages window. The New Package dialog box displays prompting you to enter a name for the new package. 3. Enter the new package name, and choose the OK button. The package name can be up to 80 characters, and all typed characters are valid. Upon choosing OK, a New Package dialog box displays. The name of the new package is indicated in the title bar of the dialog box. 4. Select a fileset and/or a script to be included in the package. Choose the down arrow button to the right of the Update Fileset and/or Update Script fields to display the list of existing filesets and scripts. Select the desired items from the drop-down lists. NOTE: A package must include either one fileset or one script, or both. 5. Select the scope to receive the package. Choose the down arrow button to the right of the Update Scope field to display the list of existing scopes. Select a scope from the drop-down list. NOTE: A scope must be assigned to the package. 6. Assign the package's Start Date. Enter the date on which the package is to be distributed. The current date appears as a default in this field. Use the up/down arrow buttons to the right of the Start Date field to scroll to the desired date, or press the key to display a calendar from which a date can be selected. 7. Assign the Active or Inactive status to the package. Check the "Update active when saved" option to automatically place the package in an active state upon saving the package. (An active package will get distributed automatically on its assigned start date.) If this field is not checked, an Inactive status will be assigned to the package. An inactive package will not get distributed automatically on its assigned start date. 8. Specify the package's update option. The selected Update Option instructs the software distribution update program how it should interact with the receiving workstation user at login time. The four Update Options are: o Force upgrade at next login - This option forces the package's receipt on the user at the next login. If an error occurs, the distribution is halted so the administrator can address the problem and reschedule the package. o User optional until [DATE] and then [ABANDON, FORCE] update - This option allows the user to refuse the package until the indicated DATE. After the DATE, the package is either abandoned or forced to be received by the user. o User optional, prompt user [# TIMES] and then [ABANDON, FORCE] update - This option allows the user to refuse the package a certain number of times (# TIMES). After the threshold is reached, the package is either abandoned or forced to be received by the user. o Run this package always - This option forces the package's receipt on the user at each and every login. This update option is most useful in situations where system variables are being modified directly by users. 9. Specify the target path in which the fileset should be decompressed. A default path must be assigned to the package. The default path is the target path in which the distributed software (i.e., fileset) is to be installed or copied. The default path can be: o entered as a hard-coded drive mapping and directory combination (e.g., C:\BIN\DRIVERS). o entered as a hard-coded server, volume and directory combination (e.g., SERVER/VOLUME:\DIR or VOLUME:\DIR). If a server is specified, then the user receiving the package must be attached to the server. o reliant upon a system configuration found at the receiving workstation. Reliance is implemented by using one of the following target default path options available from the drop down list associated with this field: - [BOOT_ROOT] - the root of the receiving machine's boot disk - [HDRIVE] - the receiving machine's first hard drive - [NDRIVE] - the receiving machine's first network drive - [NETCFG] - path to the receiving machine's network configuration (which must be in the path) - [WINDIR] - the receiving machine's Windows directory (the directory in which the login module finds WIN.INI - this directory must be in the path) - [WINSYSDIR] - the receiving machine's Windows\System directory (directory in which the login module finds USER.EXE - this directory may be in the SYSTEM directory below WINDIR, or in the path) These variables can be used in combination with a hard-coded value (e.g., [WINSYSDIR]\TEMP). In this case, the backslash character (\) is required and the variable name must be first. If a specified directory does not exist, it will be created. If desired, check the "Allow user to override installation path" option to allow the user at the receiving workstation to override the selected path. 10. To define advanced package options, choose the Advanced button. The Advanced Options dialog box displays. The advanced package options consist of the following categories: o Windows Error Options - options associated with how the software distribution update program should react in the event that the Windows directory is not discovered at a receiving workstation. o Fileset and Script Options - options which define the execution precedence for the package's fileset and script (e.g., which one the software distribution update program should run first at the receiving workstation). o Script Error Options - options associated with how the software distribution update program should react in the event of script errors. (The script function error codes are detailed in Chapter 22 of this manual, "Software Distribution Script Language.") NOTE: Several script functions may return a non-zero value that is not considered to be an error. For example, the FINDFILE function returns a -1 if the file is not found; the STRCOMPARE function returns non-zero value if the two strings are not equal. You might want to disable the Script Error Options when using functions that return non-zero values even when successful. 11. When all package attributes are defined, choose the Save button. 24.2.1 Editing Packages Editing a package may be necessary in order to modify package attributes. Use the following procedure to edit the attributes of a package. The procedure assumes that you have already chosen the Packages command from the Tools menu to display the Packages window. 1. To edit package attributes, select the package from the Packages window, and choose the Edit button. A package can also be selected for edit by double clicking on the package name in the Packages window. The Edit Package dialog box displays showing the configuration of the selected package. The fields and options in this dialog box are identical to the New Package dialog box. The name of the package being edited displays in the title bar of the Edit Package dialog box. 2. Modify the package attributes. Changes can be made to any field except the Update Scope, Update Fileset and Update Script fields. NOTES: a - Although the package's scope, fileset and script cannot be changed, their definition can be changed. For example, if Scope ABC is assigned to the package, you cannot assign Scope XYZ to the package but you can edit the members of scope ABC. b - If a package fails, it can be re-distributed to a user by first removing the user from the scope and saving the edited scope, and then adding the user back into the scope and again saving the edited scope. Be careful when doing this because editing a scope changes all instances of the scope (i.e., even those included in packages). If the distribution of a package has already begun, the changes made to the package take effect on the next node in the scope to receive the package. 3. Choose the Save button. The Packages window re-displays. NOTE: To display the Software Distribution Log History details associated with a package, highlight the package in the Packages window and choose the Details button. The Log Details dialog box displays showing the details for the selected package. This dialog box is discussed in Chapter 25. 24.3 Managing Packages 24.3.1 Prioritizing Packages The priority with which each package is run is determined by its position in the Packages window. Packages that have the same Start Date are distributed in the order in which they are listed. To modify a package's run time, highlight the package in the Packages window, and choose either the Up or Down buttons. The highlighted package will be moved in the selected direction. For example there are two packages scheduled to be distributed on 1/12/1994. Because of their position in the list of packages, WIN_INI will be distributed before UPDATED SYSTEM FILES. To change their distribution order, highlight the UPDATED SYSTEM FILES fileset and choose the up arrow button. Also note that the status of the TUTORIAL package is "Complete (A)." The (A) indicates that although the package has been distributed to all workstations in the scope, the package is still active. Therefore, if the package's scope is edited to include additional nodes, the package will automatically get distributed to those new nodes. 24.3.2 Renaming Packages Changing the name of an existing package renames the package in the Packages window. Use the following procedure to rename a package. The procedure assumes that you have already chosen the Packages command from the Tools menu to display the Packages window. NOTE: Actively scheduled packages can be renamed. 1. To rename a package, select the package from the Packages list, and choose the Rename button. The Rename Package dialog box displays prompting you to enter a new package name. 2. Enter the new package name, and choose the OK button. The new package name displays in the Packages window, and the old name is removed. All attributes of the old package are preserved in the renamed package (i.e., the package's scope, script and/or fileset definitions do not change). 24.3.3 Activating/Deactivating Packages New packages are assigned the Active status if the Update Active when Saved option is selected. An active package automatically gets distributed upon reaching its assigned Start Date. An inactive package will not get distributed until it is re-activated. The status indication of a selected package in the Packages window toggles between Active/Inactive by choosing the Activate/Deactivate toggle button in the Packages window. The status of a completed package (i.e., a package that has been sent to all nodes in its scope) remains active. Its status is indicated by "Complete (A)." By highlighting the completed package and choosing the Deactivate toggle button, the status changes to "Complete (I)" which indicates an inactive status. 24.3.4 Deleting Packages Use the following procedure to delete a package. The procedure assumes that you have already chosen the Packages command from the Tools menu to display the Packages window. NOTE: Actively scheduled packages cannot be deleted. To delete a package with an Active status, first make the package status Inactive by highlighting the package and choosing the Deactivate button. Then perform the Delete action. 1. To delete a package, select the package from the Packages window, and choose the Delete button. A prompt displays asking you to confirm the deletion. 2. Choose the Yes button to delete the package. If deleted, the package name is removed from the Packages window. NOTE: Deleting a package does not delete the associated log entry in the Software Distribution Log History dialog box. 24.4 The Package Timer The Packages window displays the status of each scheduled package. Status information includes the number of workstations in the package's scope (Total), the current number of successful updates (Done) and the total number of failed attempts at performing an update (Errors). The window contents are updated according to a defined package timer interval. Use the following procedure to set the package timer and define the interval at which the Packages window data is updated. 1. Choose the Distribution command from the Administration menu. From the sub-menu that displays, choose the Set Package Timer command. The Set Package Timer dialog box displays. 2. Enter the time interval at which the Packages window should be updated, and choose the OK button. Enter the time in seconds. (The default is 30 seconds.) The information in the Packages window will be updated at the defined interval. NOTE: The status of the Packages window can also be updated on demand by choosing the Distribution command from the Administration menu. From the sub-menu that displays, choose the Query Now command. 25.0 Monitoring Software Distribution Chapter 24 discussed the creation and management of packages. This chapter discusses the procedures for using the Software Distribution Log History dialog box to monitor the success of distributed packages. NOTE: This chapter pertains to BrightWorks. 25.1 Introduction The chronological events associated with scheduled packages can be viewed from the Software Distribution Log History dialog box. The log history provides the information necessary for monitoring the success or failure of a distributed package. For example, if package WINUPDATE is distributed to a scope having three members, the installation of the software and update details for all three receiving workstations can be verified via the log history details. 25.1.1 Access to the Software Distribution Log The Software Distribution Log History dialog box is displayed by choosing the Distribution command from the Administration menu. From the sub-menu that displays, choose the View Distribution Log command. The Software Distribution Log History dialog box is also displayed by choosing the Details button in the Packages window. 25.1.2 What's in this Chapter The following chart describes the sections in this chapter: SECTION DESCRIPTION The Software Distribution Log Describes procedures for viewing and maintaining Log history details. 25.2 The Software Distribution Log 25.2.1 Viewing Log History Details Use the following procedure to monitor and maintain the log history of distributed packages. 1. Choose the Distribution command from the Administration menu. From the sub-menu that displays, choose the View Distribution Log command. The Software Distribution Log History dialog box displays. The history log provides a summary of all scheduled packages. The following information is provided for each package: o Start Date - the date the package will be distributed o Total - the total number of workstation in the package's scope o Done - the number of successful updates so far o Errors - the total number of failed attempts at performing an update NOTE: The completed updates (Done column) may be greater than the number of users scheduled to receive a package (Total column). This can occur as a result of rescheduling packages or when using the "Run this package always" update option during package scheduling. 2. To view the individual events of a package, select the package from the Software Distribution Log History dialog box, and choose the Details button. A package can also be selected by double clicking on the package name in the Software Distribution Log History dialog box. The Log Details dialog box for the selected package displays. In addition to the distribution Date/Time and target Site Name, the Details of the package's chronological events are shown in three lines: o Identification of the target workstation - node address, user name o Additional target workstation information - location, asset tag o Results - some possible results are: - Package installed successfully. - Error [#]: Script "[Script name]" has not been completed successfully. NOTE: The error numbers related to unsuccessful script execution are documented in Chapter 22 of this manual, "Software Distribution Script Language." Non zero error numbers only display if the corresponding option was selected when the package was created. For instructions on defining "advanced package options," refer to the previous chapter. 3. To delete a log entry, select the package from the Software Distribution Log History dialog box, and choose the Delete button. The package is removed from the list of scheduled packages. NOTE: A log entry cannot be deleted if its associated package still exists. 4. Choose the OK button to close the Software Distribution Log History dialog box.